SDU Automation Tool — Project（M2 ship-ready 5/22）

SDU 自动化决策工具工程目录。承接 architecture_docs/01_业务流程梳理.md v1.1 的 Block A MVP 目标，按"解耦 CLI POC + 薄编排"实现（决策 D-08）。

M2 已完整 ship 5/22（3 天完成，提前 2.5 周）。详见 architecture_docs/M2_progress.md + handover.md。

旧的 sdu_automation_tool/、function_pocs/、capability_extractor_poc/ 等不要再继续往里加东西——它们要么被搬进这个目录、要么作为历史快照保留。

---

1. 一句话项目结构（M2 末态）

Project/
├── main.py                           ← 跑 01-05 assessment prep (Phase A2-A3, 出 talking points)
├── observe.py                        ← M3 新加: 跑 15+06 observation 实时旁听 (Phase A4)
├── build_capability_profile.py       ← M2 新加: 扫 inputs/ → L1+L2 → L3 → 11_renderer 一条命令
├── orchestrator/                     ← 薄编排层
│   ├── pipeline.py                   ← BLOCK_A_SEQUENCE: 01→02→03→04→05
│   └── task_registry.py              ← 状态记录 JSONL
├── pocs/                             ← 一个 POC 一个子目录，独立 CLI 可跑
│   ├── 00_capability_extractor/      ← L1+L2 抽取（profile 前置）
│   ├── 01_docx_extractor/            ← docx → 结构化 JSON
│   ├── 02_process_steps/             ← extraction → 02 steps
│   ├── 03_functional_requirements/   ← extraction + steps → FRs
│   ├── 04_capability_comparator/     ← M2 真版: steps + profile → per-step finding
│   ├── 05_talking_points/            ← M2 真版: steps + 04 + profile → talking points JSON
│   ├── 10_capability_extractor_L3/   ← M2 新建: 跨项目聚合 + LLM enrichment + curated merge
│   ├── 11_profile_renderer/          ← M2 新建: profile.yaml → PO 友好 MD
│   └── 13_talking_points_renderer/   ← M2 新建: 05 JSON → PO 友好 MD (deterministic)
├── scripts/                          ← M2 新加: 一次性辅助工具
│   └── analyze_failure_cases.py      ← xlsx 历史 decommission → failure_cases curated overlay
├── shared/                           ← 跨 POC 共用资产
│   ├── azure_client.py               ← Azure OpenAI client (call_json + call_text)
│   ├── capability_profile.yaml       ← M2 真产出: 2 项目聚合 + curated merge
│   ├── capability_profile_curated.yaml  ← 手编 overlay (failure_cases 等)
│   ├── capability_profile_generated.yaml ← LLM 跑的版本 (curated merge 前)
│   ├── capability_profile_report.md  ← M2 真产出: PO 友好能力报告
│   └── .analysis/                    ← analyze_failure_cases 输出 (audit + curated snippet)
├── schemas/                          ← 跨 POC 复用的 dataclass（待填）
├── config/global.yaml                ← 全局配置
├── runs/                             ← 每跑一次任务的产物聚在 runs/<task_id>/
├── inbox/                            ← 投放待处理 SOP docx
├── .env.example                      ← Azure 凭据模板
├── README.md                         ← 本文
└── HOW_TO_RUN.md                     ← 实战指南快速入口（详见 architecture_docs/operations_manual.md）

2. 工程原则（钉死，改之前先讨论）

1. POC 之间用 file 通信，不用 import 函数。 Orchestrator 也是 spawn subprocess，不直接 import POC 内部函数。这是为了让每个 POC 可独立 CLI 测试 / 单独迭代。
2. Config 分两层。 全局放 config/global.yaml；每个 POC 自己的 prompt / weights / 阈值放 pocs/<poc>/config.yaml（或 cli.py 顶常量）。Secrets 放 .env（不进 git）。
3. 同一个 task 的所有产物聚在 runs/<task_id>/。 不要散在每个 POC 自己的 outputs/ 下。POC 单独调试时还是写自己 outputs/（不冲突）。
4. Shared 抽得保守。 目前只抽 azure_client.py。其它（retry、log format）让前 2-3 个 POC 自己写，重复 3 次再抽。Premature abstraction 比 duplication 更痛。
5. 【Standing Rule】所有 POC + 工具必须 load_dotenv(override=True) —— dotenv 默认不覆盖已有 env vars。cmd 里 set AZURE_OPENAI_API_KEY=... 过老 key 就会屏蔽 .env，表现 401。建议加 fallback chain（cwd .env → Project root .env → sibling 02_process_steps/.env），见 04/05/scripts/analyze_failure_cases 实现
6. 【Standing Rule】wrapper / 工具 dry-run 必须 isolated 到 backup dir，不能覆盖正式 shared/ —— build_capability_profile.py 的 dry-run 写到 shared/.dryrun/ 就是这条 standing rule 的落地
7. 【Standing Rule】deterministic 聚合 lists 不要字母 sort + 不要随便 cap —— L3 primary_tools 字母排序 cap 8 曾导致 Office VBA 压住 UiPath bug（5/22 fix 改 Counter most_common 去 cap）
8. JSON-first: 04/05 输出 JSON 是 source（下游 LLM review / 06_streaming_observation 消费）；11_renderer 出 markdown 和 13_renderer 出 markdown 都是 view。两份都保留

3. 启动

REM 1. 装依赖
pip install -r pocs\01_docx_extractor\requirements.txt
pip install -r pocs\02_process_steps\requirements.txt
pip install -r pocs\03_functional_requirements\requirements.txt
pip install openpyxl python-dotenv  REM scripts/ 需要

REM 2. 配 Azure 凭据 (Project root 放一份 .env 让所有 POC fallback 找到)
copy .env.example .env
REM 编辑 .env 填实际值

REM 3. Phase A2-A3: 跑端到端 SOP assessment prep (01-05 → talking points)
python main.py --task-id <task_id> --input inbox\<sop>.docx
python pocs\13_talking_points_renderer\cli.py ^
    --input runs\<task_id>\05_talking_points.json ^
    --output runs\<task_id>\05_talking_points.md

REM 4. Phase A4 (几天后, observation 会议时): 跑 15+06 实时旁听
python observe.py --task-id <task_id> --audio path\to\zoom.mp4
REM 或者已有 transcript:
REM python observe.py --task-id <task_id> --transcript path\to\transcript.json

REM 5. (可选) 加新 source project 重建 profile
python build_capability_profile.py

详见 HOW_TO_RUN.md 快速入口 + architecture_docs/operations_manual.md 完整 cookbook。

4. 跟旧目录的关系

旧位置	新位置	状态
function_pocs/01_docx_extractor	Project/pocs/01_docx_extractor	已复制（含 output/sample 作历史快照）
function_pocs/02_process_steps	Project/pocs/02_process_steps	已复制
function_pocs/03_functional_requirements	Project/pocs/03_functional_requirements	已复制
capability_extractor_poc	Project/pocs/00_capability_extractor	已复制（剔除大体积 inputs/outputs）
sdu_automation_tool/	—	不迁移，历史参考
previous project/	—	历史参考
Talking_Point_POC / POC/	—	v1.1 标准已重做为 pocs/05_talking_points

5. 当前里程碑状态

• M1 (W1-W2)：✅ 5/20 完成（提前 1.5 周）
• M2 (W3-W5)：✅ 5/22 完整 ship（3 天完成，提前 2.5 周）
• M3 (W6-W8)：🔴 待启动 —— A3+A4 离线 + PO demo #1（06_streaming_observation 离线 + 12_profile_curator）；可能根据 PO v4 demo 反馈调整

详细路线图见 architecture_docs/03_开发路线图.md，M2 详细日志见 architecture_docs/M2_progress.md。

6. 给接手的人

如果你是接续这个项目的下一个开发者或 AI：先读 architecture_docs/handover.md，然后回到这里。operations_manual.md 是日常工作 cookbook。