diff --git a/.doc/archive/ops/2026-09-14-software-project-bootstrap-plan.md b/.doc/archive/ops/2026-09-14-software-project-bootstrap-plan.md new file mode 100644 index 00000000..b278aaba --- /dev/null +++ b/.doc/archive/ops/2026-09-14-software-project-bootstrap-plan.md @@ -0,0 +1,51 @@ +--- +title: "纯软件项目自举工作流方案" +status: done +created: 2026-09-14 +updated: 2026-09-14 +owner: Codex +branch: feature/software-project-bootstrap-plan +worktree: "-" +mutex: workflow-design +--- + +# 纯软件项目自举工作流方案 + +## 目标 + +基于当前 Agent-System 的真实能力,设计一套可创建、可配置、可冻结、可执行、可验收的纯软件项目自举工作流,并明确复用智能体小队、文档模板、权限与阶段门禁的实施路线。 + +## 范围 + +- 当前项目创建、工作流、阶段、文档、智能体小队和 UI 能力盘点 +- 纯软件项目的创建选项、阶段模型、交付物、门禁、角色与小队设计 +- 从最小可用版本到完整自举闭环的实施拆分、数据迁移、API/UI 与验收计划 + +## 非目标 + +- 本轮不修改 Go、React、数据库迁移、模板或智能体配置 +- 不把医疗器械合规要求默认带入纯软件项目 +- 不宣称尚未实现的方案已经可用 + +## 步骤 + +1. [x] 盘点当前实现与可复用能力 +2. [x] 完成详细系统设计和创建向导设计 +3. [x] 给出分阶段实施与真实验收计划 +4. [x] 更新 FEATURE-MATRIX、CURRENT 并完成文档校验 + +## 验收标准 + +- [x] 方案覆盖工作流、文档、智能体小队、角色权限、项目创建选项、状态机、API/UI、迁移和验收 +- [x] 清楚区分已实现、可复用、需新增和暂缓项 +- [x] 自举机制有边界、有人工确认点且不会让智能体自行修改治理规则 + +## 相关链接 + +- Research: [../../ops/research/2026-09-14-software-project-bootstrap-current-state.md](../../ops/research/2026-09-14-software-project-bootstrap-current-state.md) +- Design: [../../system-design/2026-09-14-software-project-bootstrap-workflow.md](../../system-design/2026-09-14-software-project-bootstrap-workflow.md) +- Checklist: [../../ops/checklists/2026-09-14-software-project-bootstrap-acceptance.md](../../ops/checklists/2026-09-14-software-project-bootstrap-acceptance.md) + +## 证据 / 备注 + +本轮为设计任务;所有当前态结论已回链源码、迁移或现有测试报告。主方案 599 行,验收计划 207 行;`git diff --check` 通过,相关文档 84 条相对链接校验无坏链。未运行产品功能测试,验收清单全部保持 `NOT RUN`。 diff --git a/.doc/ops/CURRENT.md b/.doc/ops/CURRENT.md index 101ff681..8bb85144 100644 --- a/.doc/ops/CURRENT.md +++ b/.doc/ops/CURRENT.md @@ -12,6 +12,7 @@ | owner | task | branch | worktree | mutex | status | |-------|------|--------|----------|-------|--------| +| Codex | software-project-bootstrap-plan | feature/software-project-bootstrap-plan | - | workflow-design | done | | Cursor | chat-history-refresh-remediation | fix/chat-history-refresh | - | chat | in_progress | | Codex | conversation-intent-runtime-state | fix/conversation-intent-state | .worktrees/fix-conversation-intent-state | intent | in_progress | | Cursor | document-revision-wave1-6-implementation | feature/document-revision-management | - | docgov | done | @@ -73,6 +74,7 @@ | DOCREV ADR | [../adr/2026-09-13-document-version-boundary.md](../adr/2026-09-13-document-version-boundary.md) | | DOCREV 管理测试 | [../test-reports/2026-09-13-document-revision-management-test-report.md](../test-reports/2026-09-13-document-revision-management-test-report.md) | | DOCREV 运行时 UI Round20 | [../test-reports/2026-09-14-document-revision-runtime-ui-test-report.md](../test-reports/2026-09-14-document-revision-runtime-ui-test-report.md) | +| 纯软件项目自举设计 | [../system-design/2026-09-14-software-project-bootstrap-workflow.md](../system-design/2026-09-14-software-project-bootstrap-workflow.md) | | SSE/幂等审计 | [../audit/2026-09-13-document-revision-sse-idempotency.md](../audit/2026-09-13-document-revision-sse-idempotency.md) | | 质量门禁自污染审计 | [../audit/2026-09-13-document-revision-quality-gate-self-pollution.md](../audit/2026-09-13-document-revision-quality-gate-self-pollution.md) | | 当前文档路由审计 | [../audit/2026-09-13-document-revision-active-doc-routing.md](../audit/2026-09-13-document-revision-active-doc-routing.md) | diff --git a/.doc/ops/checklists/2026-09-14-software-project-bootstrap-acceptance.md b/.doc/ops/checklists/2026-09-14-software-project-bootstrap-acceptance.md new file mode 100644 index 00000000..a940aaff --- /dev/null +++ b/.doc/ops/checklists/2026-09-14-software-project-bootstrap-acceptance.md @@ -0,0 +1,207 @@ +--- +title: "纯软件项目自举工作流验收清单" +status: planned +created: 2026-09-14 +updated: 2026-09-14 +related_task: "ops/long-term/2026-09-14-software-project-bootstrap-implementation.md" +--- + +# 纯软件项目自举工作流验收清单 + +> 本文件是未来实施验收计划,当前全部用例均为 `NOT RUN`。不得把设计评审、stub、接口注入或静态 JSON 写成真实功能 PASS。 + +## 0. 验收分层 + +| 层 | 范围 | 可否代替真实 UI | +|----|------|-----------------| +| L1 | manifest、profile、模板、quality gate 单元测试 | 否 | +| L2 | PostgreSQL 迁移、领域服务、API、鉴权、并发 | 否 | +| L3 | 前端组件、类型、build | 否 | +| L4 | stub 小队和固定输出工程测试 | 否 | +| L5 | 真实 PI Agent Runner | 否,仍需页面验证 | +| L6 | Ubuntu Server 无头浏览器真实页面操作 | 是,最终验收 | + +## 1. 工程门禁 + +### Manifest 与目录 + +- [ ] `software_bootstrap` 和 `software_delivery` 均可校验、发布和退役 — 证据:NOT RUN +- [ ] 非 published / 非 selectable / 不兼容 domain 的工作流不出现在项目目录 — 证据:NOT RUN +- [ ] 新版本不会改变已激活实例的 manifest/template/profile hash — 证据:NOT RUN +- [ ] 医疗现有三工作流及黄金用例无回归 — 证据:NOT RUN +- [ ] 不再依赖“三正式 key”或固定文档数量硬编码 — 证据:NOT RUN + +### 数据与迁移 + +- [ ] 空数据库从 schema 1 升级并创建项目类型、profile、source binding — 证据:NOT RUN +- [ ] 旧数据库升级不误分类既有项目 — 证据:NOT RUN +- [ ] secret 只存引用,数据库、文档、日志和 prompt 无明文 — 证据:NOT RUN +- [ ] 项目、成员、planning instance、模板账本创建具备幂等事务语义 — 证据:NOT RUN +- [ ] 应用重启后项目、来源、plan、阶段和文档版本可恢复 — 证据:NOT RUN + +### 授权与治理 + +- [ ] 非成员无法列出项目、对话、来源、文档、SSE、RAG 或 Agent 结果 — 证据:NOT RUN +- [ ] 非创建者无法激活、推进、选择下一流程或终止 — 证据:NOT RUN +- [ ] 客户端伪造 task/stage/duty/repo path 被服务端拒绝 — 证据:NOT RUN +- [ ] collaborative 模式三权必须不同人 — 证据:NOT RUN +- [ ] solo 只允许 creator acknowledgement 且页面显示“未独立评审” — 证据:NOT RUN +- [ ] controlled profile 禁止 solo — 证据:NOT RUN +- [ ] 激活后 workflow/template/profile/duty 不能直接修改 — 证据:NOT RUN + +### 小队与文档 + +- [ ] 每个 executor/template/quality gate/profile 均注册且可解析 — 证据:NOT RUN +- [ ] 正式任务只能从冻结 doc_task_instance 启动 — 证据:NOT RUN +- [ ] 步骤预算、timeout、工作区边界和 manifest 生效 — 证据:NOT RUN +- [ ] 失败、跳过、fallback、未验证项不会被改写成 PASS — 证据:NOT RUN +- [ ] 非医疗默认小队不包含 regulatory — 证据:NOT RUN +- [ ] 纯软件模板和回复无医疗默认术语污染 — 证据:NOT RUN + +## 2. Ubuntu Server 真实 UI 前置 + +- [ ] 占用 CURRENT 集成槽位 — 证据:NOT RUN +- [ ] `go vet ./...`、`go test -short ./...`、前端测试/build 通过 — 证据:NOT RUN +- [ ] PostgreSQL、app、真实 PI Runner、MiniMax 均 ready — 证据:NOT RUN +- [ ] 明确记录 commit、schema、镜像、模型、BASE_URL 和开始时间 — 证据:NOT RUN +- [ ] 使用官方 Playwright Chromium 容器;宿主无需安装浏览器 — 证据:NOT RUN +- [ ] 若容器不可用,才执行 `npx playwright install --with-deps chromium` — 证据:NOT RUN +- [ ] 禁止 `page.route`、mock/stub、直接写数据库或伪造 API 输出 — 证据:NOT RUN + +推荐运行形态: + +```bash +docker run --rm --network host --ipc host \ + -e BASE_URL=http://127.0.0.1:3100 \ + -v "$PWD:/work" -w /work \ + mcr.microsoft.com/playwright:v1.63.0-noble \ + npx playwright test +``` + +## 3. 真实 UI 用例 + +### UI-SW-00 项目类型与向导 + +- **Input**:管理员登录;打开创建项目;选择 non-medical software。 +- **Expected**:展示七步软件字段;不出现医疗器械固定标题、临床用途或 NMPA 默认值。 +- **Evidence**:截图、trace、console/network 日志。 +- **Status**:NOT RUN。 + +### UI-SW-01 既有项目单人创建 + +- **Input**:`existing_self_bootstrap + standard + solo + docs_only`;页面上传允许的仓库说明和文档。 +- **Expected**:确认页显示 creator acknowledgement 和“未独立评审”;一次提交后项目、成员、plan 和模板可见;重复提交不创建第二项目。 +- **Evidence**:截图、项目 ID、页面列表、trace。 +- **Status**:NOT RUN。 + +### UI-SW-02 协作项目职责 + +- **Input**:创建 collaborative 项目并选择至少三名成员。 +- **Expected**:逐文档分配 author/reviewer/approver;重复人员不能激活;修正后预览成功。 +- **Evidence**:职责矩阵截图、错误提示、激活预览。 +- **Status**:NOT RUN。 + +### UI-SW-03 激活冻结 + +- **Input**:保存 plan、查看预览、确认激活;随后尝试修改模板、profile 或职责。 +- **Expected**:实例引用固定版本/hash;直接修改被拒绝;409 时展示差异且不自动重试。 +- **Evidence**:预览、实例详情、拒绝提示。 +- **Status**:NOT RUN。 + +### UI-SW-04 真实基线小队 + +- **Input**:在对话框输入“请基于我上传的项目资料,正式启动现状梳理并生成现状审计”。 +- **Expected**:页面可见真实小队、角色、步骤、进度、真实助手回复;生成 `current_state_audit`,不是聊天长回答。 +- **Evidence**:对话、步骤条、文档截图、trace/video。 +- **Status**:NOT RUN。 + +### UI-SW-05 事实等级与证据 + +- **Input**:打开现状审计和架构基线。 +- **Expected**:confirmed/inferred/unverified 可区分;high 问题有来源;找不到的信息明确写未验证。 +- **Evidence**:文档截图、来源清单、版本账本。 +- **Status**:NOT RUN。 + +### UI-SW-06 软件语义隔离 + +- **Input**:使用不含医疗内容的软件项目材料跑完整 bootstrap。 +- **Expected**:项目、回复、模板和文档中不出现临床、注册、NMPA、GB 9706、CDMO 等默认语义。 +- **Evidence**:页面全文搜索和截图;任何命中逐条说明来源。 +- **Status**:NOT RUN。 + +### UI-SW-07 文档变更链 + +- **Input**:人工编辑一个块并保存;再通过真实对话要求小队更新同一文档。 +- **Expected**:revision 增长、刷新保留;agent candidate 有 diff、风险、项目/文档影响和开放问题;确认/拒绝行为正确。 +- **Evidence**:版本、revision、overlay、报告截图。 +- **Status**:NOT RUN。 + +### UI-SW-08 阶段门禁与创建者确认 + +- **Input**:文档未批准时尝试推进;完成审核批准后等待通知;创建者确认推进。 +- **Expected**:未批准时列出 blocker;就绪只通知一次;不自动推进;非创建者不可推进。 +- **Evidence**:readiness 面板、通知、阶段前后截图。 +- **Status**:NOT RUN。 + +### UI-SW-09 Bootstrap 就绪 + +- **Input**:完成所有启用阶段并打开 readiness。 +- **Expected**:汇总风险、依赖和未验证项;存在 high blocker 时不可批准;通过后 workflow completed。 +- **Evidence**:readiness 文档、阶段树、审计事件。 +- **Status**:NOT RUN。 + +### UI-SW-10 下一工作流建议 + +- **Input**:bootstrap 完成。 +- **Expected**:页面建议 `software_delivery`,但不自动创建或激活;仅创建者确认后生成新的 planning instance。 +- **Evidence**:建议卡、确认前后实例列表。 +- **Status**:NOT RUN。 + +### UI-SW-11 Delivery 迭代 + +- **Input**:建立 change brief 和 implementation plan,上传外部实现的 change manifest 与真实测试报告。 +- **Expected**:trace 到 bootstrap requirements;失败/跳过测试阻断发布;用户确认后完成迭代。 +- **Evidence**:文档血缘、测试报告、门禁、release notes。 +- **Status**:NOT RUN。 + +### UI-SW-12 权限负例 + +- **Input**:非成员和 viewer 登录;篡改 URL 中 project/doc/run/source ID。 +- **Expected**:服务端 403/404;页面无数据泄露;SSE 不先 flush 200。 +- **Evidence**:页面错误、network、服务端审计。 +- **Status**:NOT RUN。 + +### UI-SW-13 刷新与重启恢复 + +- **Input**:记录项目/实例/阶段/文档版本和正文;硬刷新、退出重登;仅 restart app 后再次登录。 +- **Expected**:对话、任务、阶段、文档、职责、风险、V/r 和正文一致恢复。 +- **Evidence**:pre/post state 文件和截图。 +- **Status**:NOT RUN。 + +### UI-SW-14 Agent-System 自举黄金项目 + +- **Input**:用 Agent-System 当前仓库作为只读来源,真实执行 software_bootstrap。 +- **Expected**:页面生成当前态审计、架构、需求/backlog、风险、路线图和测试策略;当前结论重新核验,不照抄历史审计;不修改仓库。 +- **Evidence**:完整对话、全部文档、版本、trace/video、来源 hash。 +- **Status**:NOT RUN。 + +## 4. 未来 controlled patch 负例 + +- [ ] repo 未绑定不能执行 — 证据:NOT RUN +- [ ] 非 allowlist 路径被拒绝 — 证据:NOT RUN +- [ ] `.env`、secret、生产 dump 排除有效 — 证据:NOT RUN +- [ ] 只在 feature worktree 写入 — 证据:NOT RUN +- [ ] 超出批准文件范围立即停止 — 证据:NOT RUN +- [ ] 测试失败不自动 merge — 证据:NOT RUN +- [ ] 批准执行不等于批准 merge/push/deploy — 证据:NOT RUN +- [ ] 保护分支直接 commit、force push、破坏性命令均被拒绝 — 证据:NOT RUN + +## 5. 完成定义 + +- [ ] L1–L5 工程门禁分别记录真实结果 +- [ ] UI-SW-00–14 全部由真实页面操作执行并留证 +- [ ] 真实 PI 回复、小队进度和所有交付文档均可在 UI 看到 +- [ ] 医疗与软件两套黄金项目均无回归 +- [ ] 刷新、重登、重启、并发和权限负例通过 +- [ ] test-report 逐项包含 Input/Expected/Actual/Verdict/Duration +- [ ] 任何 NOT RUN、fallback、失败和开放风险均如实保留 diff --git a/.doc/ops/long-term/2026-09-14-software-project-bootstrap-implementation.md b/.doc/ops/long-term/2026-09-14-software-project-bootstrap-implementation.md new file mode 100644 index 00000000..b11ef597 --- /dev/null +++ b/.doc/ops/long-term/2026-09-14-software-project-bootstrap-implementation.md @@ -0,0 +1,58 @@ +--- +title: "纯软件项目自举工作流实施" +status: planned +created: 2026-09-14 +updated: 2026-09-14 +--- + +# 纯软件项目自举工作流实施 + +## 动机 + +当前工作流引擎已经声明支持 `non_medical_software`,但创建入口、正式目录、阶段、模板、执行器和小队提示词仍以医疗器械为主。需要新增领域原生的软件项目工作流,使既有软件项目可以在系统中完成可信梳理、路线规划和后续迭代,并为安全的系统自举建立边界。 + +## 成功标准 + +- 用户可以在页面创建 greenfield/existing/legacy/self-bootstrap 软件项目; +- 项目创建、成员、planning instance 和模板账本由服务端幂等落库; +- `software_bootstrap` 可真实生成并批准项目基线、审计、需求、架构、风险、路线和验证策略; +- 完成后只建议、不会自动启动 `software_delivery`; +- delivery 可重复创建实例并承接每个迭代的计划、证据、测试和发布资料; +- 纯软件项目无医疗语义污染,医疗既有工作流无回归; +- 真实 PI 和 Ubuntu 无头浏览器黄金项目验收通过; +- 未实现受控代码执行前,系统不会直接修改项目仓库。 + +## 实施拆分 + +| Epic | 范围 | 依赖 | 验收 | +|------|------|------|------| +| SWBOOT-00 契约与 ADR | keys、profiles、领域边界、solo、错误码 | 无 | 设计评审 | +| SWBOOT-01 项目域模型 | project type/compliance/governance/source schema 与迁移 | 00 | 空库/旧库 PG | +| SWBOOT-02 工作流目录 | 适用性过滤、去三 key/固定 doc count 硬编码 | 01 | catalog/validator | +| SWBOOT-03 Bootstrap 定义 | manifest、模板、executor、quality gate | 02 | unit + stub | +| SWBOOT-04 Delivery 定义 | 可重复交付实例、血缘和交接 | 03 | instance lifecycle | +| SWBOOT-05 软件角色 profile | product/architecture/quality/security/operations | 03 | prompt golden | +| SWBOOT-06 创建向导 | preview、幂等事务、成员、七步 UI | 01/02 | API + UI | +| SWBOOT-07 对话路由 | 软件 task aliases、正式/自由任务边界、domain context | 03/05 | hard-negative | +| SWBOOT-08 阶段门禁 | 软件风险、来源 freshness、readiness、下一流程建议 | 03/04 | PG + notification | +| SWBOOT-09 真实验收 | 医疗/软件双黄金、真实 PI、重启、权限 | 03–08 | 完整 test-report | +| SWBOOT-10 受控工程执行 | repo allowlist、worktree、patch/test/merge 分段批准 | 09 后单独启动 | 安全 E2E | + +## 依赖 + +- 当前 `CHAT-INTENT-STATE` 整改需先完成或至少冻结稳定基线,否则只读梳理可能误启动写任务; +- CI PostgreSQL 隔离库和真实 PI 凭证链; +- 工作流设计器/模板发布能力保持可用; +- 文档版本运行时 Round20 能力作为文档链基线; +- 用户确认首期执行模式及 solo/collaborative 策略。 + +## 暂不启动原因 + +本轮用户要求先梳理和制定详细方案;业务代码、迁移、模板和智能体配置尚未授权进入实施。本任务保持 `planned`,启动时须从 `dev` 新建独立 feature 分支,并在 CURRENT 认领 `workflow-design`/相应拆分 mutex。 + +## 相关链接 + +- [详细设计](../../system-design/2026-09-14-software-project-bootstrap-workflow.md) +- [现状调研](../research/2026-09-14-software-project-bootstrap-current-state.md) +- [验收清单](../checklists/2026-09-14-software-project-bootstrap-acceptance.md) +- [运行时权威 ADR](../../adr/2026-09-12-workflow-runtime-authority.md) diff --git a/.doc/ops/research/2026-09-14-software-project-bootstrap-current-state.md b/.doc/ops/research/2026-09-14-software-project-bootstrap-current-state.md new file mode 100644 index 00000000..77c28712 --- /dev/null +++ b/.doc/ops/research/2026-09-14-software-project-bootstrap-current-state.md @@ -0,0 +1,72 @@ +--- +title: "纯软件项目自举能力现状" +created: 2026-09-14 +status: done +confidence: high +--- + +# 调研:纯软件项目自举能力现状 + +## 结论 + +当前系统已经具备版本化工作流、冻结实例、阶段门禁、文档三权、文档版本账本、真实 PI 小队、自由任务、上下文快照、通知和审计等可复用基础,但项目创建、正式工作流目录、模板、角色提示词和任务路由仍以医疗器械语义为主。现状不能通过把 `device_type` 改成“软件”来安全复用;应新增纯软件工作流与领域配置,同时复用治理引擎和大部分通用小队能力。 + +本结论来自当前源码和现有验收报告核对,未在本轮启动真实 PI 或修改业务代码。 + +## 证据 + +| 项 | 路径/命令 | 结果 | +|----|-----------|------| +| 项目创建 UI | `web/src/components/project/CreateProjectModal.tsx` | 标题固定“医疗器械新项目”,`deviceType` 固定“通用医疗器械”,字段与提示词均是临床/法规语义 | +| 项目创建后模板 | `web/src/App.tsx` `handleCreateProjectConfirm` | 前端本地克隆固定 7 份医疗模板,并写死 V0.1 阶段提示;不是工作流版本驱动的服务端事务 | +| 项目模型 | `internal/projectworkflow/types.go`、`00001_baseline.sql` | 仍使用 `device_type/intended_use/target_market`;没有权威 `project_type/product_domain/compliance_profile/repository_binding` | +| 工作流定义 | `internal/workflowdef/manifests/*.v2.json` | manifest 宣称支持 `non_medical_software`,但阶段、文档与执行器仍是商务、注册、CDO、医疗验证语义 | +| 正式目录限制 | `internal/workflowdef/catalog_policy.go`、`projectinstance/validator.go` | 项目只能选择 `main/product_manager/test_manager`,还存在“三正式工作流”和固定文档数硬编码 | +| 工作流治理 | `internal/projectinstance/service.go`、`stage_service.go` | planning、激活预览、冻结快照、单活动实例、文档批准门禁、创建者确认推进均已实现,可直接复用 | +| 运行时权威 | `.doc/adr/2026-09-12-workflow-runtime-authority.md` | 运行任务必须从冻结实例解析 executor、模板和三权,禁止客户端覆盖 task/stage/duty | +| 小队角色 | `internal/squad/roles.go` | organizer/searcher/engineer/market/finance/writer 具有较强通用性;regulatory 是医疗专属;leader 仍绑定水木东方医疗器械 CDMO | +| 小队治理 | `internal/squad/workflow.go`、`gov.go`、`workspace.go` | 已有工作区隔离、步骤冻结、预算、轨迹、黑板、质量门禁、断点续跑,可复用 | +| 自由任务 | `internal/coordinator/router.go`、`internal/squad/planner.go` | 已有复杂任务升级与 ad-hoc 四步小队,但自动模板和专家派生仍含医疗措辞,不能当正式软件工作流 | +| 模板 | `templates/docs/*.md` | `system_reqs`、部分 `user_requirements` 可抽取通用骨架;research/test/prelim/quote 含法规、临床、电气安全或 CDMO 语义 | +| 文档版本 | `.doc/test-reports/2026-09-14-document-revision-runtime-ui-test-report.md` | 真实 UI 已验证版本、修订、确认/拒绝、并发、权限和重启恢复,可作为软件文档链路基础 | +| 发布状态 | `.doc/status/FEATURE-MATRIX.md`、`remediation/gap-matrix.md` | 全系统仍 `production_ready=no`;新方案不得绕过现有 CHAT-INTENT、CI 和真实 PI 门禁 | + +## 可复用与需新增边界 + +| 能力 | 判定 | 处理方式 | +|------|------|----------| +| 工作流版本、冻结、阶段推进 | 直接复用 | 不新造运行时引擎 | +| 文档三权与版本账本 | 直接复用 | 按纯软件文档类型挂载 | +| organizer/searcher/writer | 复用为主 | 去除组织和医疗专属措辞 | +| engineer/leader | 复用内核 | 增加软件领域 profile;leader 改为领域中立交付负责人 | +| regulatory | 条件复用 | 仅合规配置需要时启用,不作为非医疗默认角色 | +| market/finance | 可选复用 | 商业产品启用,内部工具默认关闭 | +| 自由任务与动态角色 | 辅助复用 | 用于非标准文档;不得替代已发布工作流和冻结任务契约 | +| 项目创建向导 | 需重构 | 由服务端项目类型与工作流目录驱动,停止前端固定克隆 7 份模板 | +| 软件模板和质量门禁 | 需新增 | 新 task key、模板、executor、quality gate | +| 仓库绑定与代码执行 | 需新增 | 分成只读盘点和受控变更两级;首期不直接改仓库 | +| 独立评审例外 | 需新增 | 单人项目明确标记“无独立评审”,不可伪造 reviewer/approver | + +## 关键差距 + +1. `product_domains` 只存在于 manifest 声明,项目本身没有权威产品域,工作流目录也未按项目域过滤。 +2. `workflow_definitions.product_domain` 是单字符串,而 manifest 是多域数组,适用性模型存在双重表达。 +3. 创建项目与创建成员不是同一后端事务,模板又由浏览器本地克隆;跨设备和失败恢复的事实源不完整。 +4. 当前三权校验强制三个不同用户,无法诚实支持个人自举项目。 +5. 当前阶段 readiness 主要检查“必需文档已批准”,尚不能表达测试证据、开放高风险、变更请求和构建结果等软件门禁。 +6. 当前 `SupportedTasks`、意图关键词、知识检索和模板都绑定既有 task key,新增软件工作流必须成套扩展。 +7. PI 小队只能在受控工作区生成文件;没有经授权的仓库 worktree、测试、补丁审查和合并控制面。 + +## 开放问题 + +- 首个使用者是单人还是至少三人协作,这将决定是否启用独立三权或“创建者确认、未独立评审”策略。 +- 目标项目仓库如何接入:浏览器上传快照、只读 Git URL,还是服务器受控本地路径。 +- 首期目标是“梳理与计划”还是要同时支持生成代码补丁;建议先交付前者。 +- 是否需要默认启用隐私、安全或外部合规 profile;不能从“纯软件”自动推断为 `none`。 + +## 建议动作 + +- 首期新增 `software_bootstrap`,并以项目类型、治理强度和项目形态生成默认规划。 +- 第二期新增可重复实例化的 `software_delivery`,承接每个里程碑或发布。 +- 先实现 `docs_only/read_only_repo`,代码变更执行器单独立项并受 feature worktree、测试、审批和审计约束。 +- 保留现有医疗三工作流,不在原 manifest 上直接替换语义,避免回归。 diff --git a/.doc/status/FEATURE-MATRIX.md b/.doc/status/FEATURE-MATRIX.md index bc370439..b8a79566 100644 --- a/.doc/status/FEATURE-MATRIX.md +++ b/.doc/status/FEATURE-MATRIX.md @@ -19,6 +19,7 @@ | 对话 / ctxmgr | 多轮上下文、记忆、摘要 | partial | [system-design/multi-turn-dialogue](../system-design/multi-turn-dialogue/);[刷新恢复专项审计](../audit/2026-09-13-chat-history-refresh-disappears.md) | `CHAT-HISTORY-REFRESH`:作用域写入、同集授权统计、历史回填;语义摘要(D5 backlog) | `chat` | | 智能体小队 | 角色-任务-工作区-黑板 | done | [system-design/agent-squad](../system-design/agent-squad/);[test 2026-09-07](../test-reports/2026-09-07-dynamic-squad-planning-test-report.md) | 非关键步骤降级(A5/A6 backlog) | `squad` | | 工作流治理 | 三正式工作流 + 阶段门禁 | done | [remediation/three-workflows](../remediation/2026-09-12-three-workflows-strict-governance-remediation.md);[test 2026-09-12](../test-reports/2026-09-12-three-workflows-governance-remediation-test-report.md) | Phase2 设计器 partial | `workflow` | +| 纯软件项目自举 | 软件项目创建、Bootstrap 基线、Delivery 迭代与受控工程交接 | planned | [详细设计](../system-design/2026-09-14-software-project-bootstrap-workflow.md);[现状调研](../ops/research/2026-09-14-software-project-bootstrap-current-state.md);[验收计划](../ops/checklists/2026-09-14-software-project-bootstrap-acceptance.md) | 当前仅完成方案;目录/模板/执行器/创建向导/真实 PI UI 均未实施。受控代码执行单列后续 Epic | `workflow-design` | | IAM / 鉴权 | 项目级 API 鉴权 + RBAC | partial | [audit/authorization](../audit/authorization-matrix-v2.md);[刷新恢复专项审计](../audit/2026-09-13-chat-history-refresh-disappears.md) | 历史读取端点补统一会话 owner + 阶段授权;旧 API 410 标注(BUG-11 partial) | `authz` | | 文档治理 | 法定文档生命周期 + 租约 | done | [test docgov](../test-reports/2026-09-08-docgov-lifecycle-and-claiming-framework-test-report.md) | — | `docgov` | | 文档版本与修改认知 | 智能体版本边界、人工修订标记、任意版本比较、变更报告与负责人通知 | partial | [管理测试](../test-reports/2026-09-13-document-revision-management-test-report.md);[运行时 UI Round20](../test-reports/2026-09-14-document-revision-runtime-ui-test-report.md);[运行时审计](../audit/2026-09-13-document-revision-runtime-404.md);[ADR](../adr/2026-09-13-document-version-boundary.md) | **运行时 UI PASS**(6159 / V3/r2)。仍 `partial`:change report=`fallback`(真实 diff+lineage,非完整 PI 叙事)。系统级 `CHAT-INTENT` 见 gap-matrix | `docgov` | diff --git a/.doc/system-design/2026-09-14-software-project-bootstrap-workflow.md b/.doc/system-design/2026-09-14-software-project-bootstrap-workflow.md new file mode 100644 index 00000000..b7d77af0 --- /dev/null +++ b/.doc/system-design/2026-09-14-software-project-bootstrap-workflow.md @@ -0,0 +1,602 @@ +# 纯软件项目自举工作流详细设计 + +**状态**:设计完成,待评审与实施 + +**日期**:2026-09-14 + +**适用范围**:非医疗纯软件项目;既有项目梳理、绿地立项、遗留系统现代化,以及使用 Agent-System 梳理 Agent-System 自身 + +**实现状态**:本文件是目标方案,不代表功能已经上线 + +## 1. 执行摘要 + +建议给 Agent-System 增加一套领域原生的“软件项目自举套件”,而不是继续复用医疗器械 `main` 工作流: + +1. **`software_bootstrap`**:一次性建立项目事实、现状、需求、架构、风险、路线图与验收基线; +2. **`software_delivery`**:按里程碑或发布重复实例化,管理变更计划、实现证据、测试、发布和复盘; +3. 首期只做**文档与决策自举**,可读取用户上传或授权的仓库快照,但不直接修改业务仓库; +4. 后续增加**受控工程执行器**:仅在隔离 feature worktree 生成补丁,测试和人工确认后才允许合并,永不直接改 `dev/test/main`; +5. 最大限度复用现有工作流版本、冻结快照、三权、阶段门禁、文档版本账本、上下文快照、小队工作区、预算和 SSE; +6. 不复用会造成语义污染的医疗模板、法规默认步骤、CDMO 负责人提示词和硬编码阶段。 + +推荐当前用户项目的初始选择: + +| 选项 | 推荐值 | 理由 | +|------|--------|------| +| 产品域 | `non_medical_software` | 明确与医疗器械域隔离 | +| 项目形态 | `existing_self_bootstrap` | 已有项目,希望梳理并用系统反向建设自身 | +| 工作流 | `software_bootstrap@v1` | 先建立可信基线,再进入迭代 | +| 治理强度 | `standard` | 保留评审、版本和风险门禁,不引入医疗合规负担 | +| 合规配置 | `internal_control + security_baseline` | 无外部法规假设,但保留安全、权限、审计和发布证据 | +| 仓库接入 | `read_only_snapshot` | 首轮只读,避免智能体越权改码 | +| 工程执行 | `docs_only` | 先产出可评审路线图;受控补丁执行另行开启 | +| 小队 | 通用角色 + 软件 profile | 复用现有能力,排除默认 regulatory | + +## 2. 设计原则 + +### 2.1 领域与合规分离 + +`product_domain=non_medical_software` 只说明产品不是医疗器械,不代表没有安全、隐私、审计或行业约束。项目还要独立选择 `compliance_profile`。 + +### 2.2 一个权威运行链 + +沿用现有 ADR: + +```text +服务端登录主体 + → 项目成员关系 + → 已发布工作流版本 + → 项目冻结快照 + → 阶段与文档任务实例 + → executor / template / quality gate / 文档三权 + → 真实 PI 小队 + → 文档版本、审批、血缘和审计 +``` + +不得新增从前端 `task_key`、本地模板或自由对话直接绕过冻结实例的旁路。 + +### 2.3 自举不等于自治接管 + +智能体可以盘点、分析、提出变更、生成候选补丁和运行获准测试,但不能自行: + +- 改写工作流定义或权限策略; +- 修改受保护分支; +- 合并、push、发布或删除数据; +- 读取未授权 secret; +- 把推断写成已验证事实; +- 以智能体意见代替用户的阶段推进、风险接受或发布批准。 + +### 2.4 事实分层 + +所有产出必须标记: + +- `confirmed`:有源码、文档、运行证据或用户确认; +- `inferred`:基于证据推导; +- `unverified`:尚未实测; +- `decision_required`:必须由用户拍板。 + +### 2.5 工作流串联而非循环定义 + +当前引擎是线性阶段、单项目单活动实例。初期不在 manifest 中增加回环: + +```text +software_bootstrap(一次) + → 创建者确认完成 + → software_delivery(版本/里程碑 1) + → 完成 + → software_delivery(版本/里程碑 2) + → ... +``` + +每个 delivery 实例冻结自己的目标、输入、模板、责任人和验收基线,历史可审计。 + +## 3. 项目创建向导 + +项目创建改为七步服务端驱动向导。创建前可保存草稿,最终通过一次幂等事务建立项目、成员、规划实例和模板账本。 + +### 3.1 第一步:基本身份 + +| 字段 | 示例/枚举 | 必填 | 说明 | +|------|-----------|------|------| +| `name` | Agent-System 自举项目 | 是 | 项目展示名 | +| `code` | AS-BOOTSTRAP | 否 | 空时服务端生成 | +| `product_domain` | `non_medical_software` | 是 | 权威产品域 | +| `project_type` | `existing_self_bootstrap` | 是 | 见下表 | +| `product_shape` | web / SaaS / service / desktop / mobile / CLI / library / platform | 是 | 可多选 | +| `problem_statement` | 当前问题与希望达到的状态 | 是 | 替代“临床预期用途” | +| `target_users` | 内部团队、企业客户等 | 是 | 可多组 | +| `target_outcome` | 可验证结果 | 是 | 例如“建立可执行发布路线” | + +项目类型: + +| key | 用途 | 默认输入 | +|-----|------|----------| +| `greenfield` | 从零规划新软件 | 构想、用户、约束 | +| `existing_product` | 梳理已有产品 | 文档、仓库快照、问题列表 | +| `legacy_modernization` | 遗留系统改造 | 现状架构、痛点、迁移约束 | +| `existing_self_bootstrap` | 系统用自身梳理和建设自身 | 当前仓库、运行说明、历史审计、目标 | + +### 3.2 第二步:范围与成功标准 + +- 本轮必须解决的问题; +- 明确不做的范围; +- 目标里程碑和期望时间窗; +- 已知用户场景和业务约束; +- 性能、可用性、安全、隐私、兼容性、成本约束; +- 可量化成功标准; +- 允许智能体提出但不得替用户决定的事项。 + +系统生成 `TaskBrief` 预览,用户确认后作为工作流输入基线,不让小队自行漂移目标。 + +### 3.3 第三步:治理与合规 + +| 选项 | 值 | 默认 | +|------|----|------| +| `governance_profile` | lean / standard / controlled | standard | +| `team_mode` | solo / collaborative | 根据有效成员数提示,不自动猜 | +| `compliance_profile` | none / internal_control / security_baseline / privacy / custom | internal_control + security_baseline | +| `data_sensitivity` | public / internal / confidential / restricted | internal | +| `network_policy` | deny / allowlist / project-approved | project-approved | +| `execution_mode` | docs_only / read_only_repo / controlled_patch | docs_only | +| `budget_class` | light / medium / heavy | medium | + +规则: + +- `none` 只代表没有预设外部合规步骤,不关闭鉴权、审计和安全基线; +- `controlled_patch` 必须在仓库绑定、分支策略、测试命令和批准人都有效后才能选择; +- `restricted` 数据默认禁止外部联网检索; +- 合规 profile 只能增加约束,不可通过对话临时关闭。 + +### 3.4 第四步:资料与仓库来源 + +首期支持: + +1. 页面上传 Markdown、PDF、DOCX、JSON、CSV 和代码清单; +2. 浏览器上传经过用户筛选的仓库快照; +3. 服务端登记只读 Git URL 或本地允许列表路径; +4. 录入现有文档、Issue/PR 导出、测试报告和部署清单; +5. 配置明确排除目录,如 `.git`、依赖缓存、构建产物、secret 和生产数据。 + +每个来源记录 `source_type/source_ref/revision/hash/permission_scope/ingested_at`。凭证只保存 secret 引用,不进入项目文档、prompt 或审计正文。 + +### 3.5 第五步:选择工作流和强度 + +目录只展示与 `product_domain`、`project_type`、`compliance_profile` 兼容的已发布版本,并标明: + +- 版本号与发布日期; +- 默认阶段和文档; +- 各 profile 会启用/关闭的任务; +- 预计小队步骤、时间和预算; +- 需要几名独立责任人; +- 激活后冻结的项目配置。 + +首个推荐为 `software_bootstrap@v1`。不在创建时直接激活,先进入 planning。 + +### 3.6 第六步:成员与责任 + +项目角色和文档职责继续分离: + +| 项目关系 | 主要能力 | +|----------|----------| +| creator | 配置、激活、阶段推进、受控终止、选择下一工作流 | +| product_owner | 范围和验收业务意见 | +| maintainer | 技术输入、实现证据和变更建议 | +| reviewer | 对指定文档审核 | +| approver | 对指定文档批准 | +| viewer | 只读参与 | + +文档仍逐份绑定 author/reviewer/approver。 + +`collaborative` 默认三权分离。`solo` 不伪造三名用户,采用: + +- author=创建者; +- review/approve 改为 `creator_acknowledgement`; +- 页面持续显示“未经过独立评审”; +- controlled 或任何要求独立审查的 compliance profile 禁止 solo; +- 后续邀请 reviewer 后可通过受控变更升级,但不能回写历史签署。 + +### 3.7 第七步:创建预览与确认 + +确认页展示:项目类型、工作流版本、启用文档、责任人、数据来源、网络策略、小队、预算、预计耗时、冻结项和风险。服务端返回: + +```text +creation_token + plan_hash + source_hash + expected_catalog_version + expires_at +``` + +最终提交必须匹配这些值;目录、成员或来源变化返回 409 和差异,要求重新确认。 + +创建完成后: + +- 服务端事务创建项目、owner/member、planning instance 和文档模板记录; +- 前端不再本地克隆固定 7 份医疗模板; +- 页面打开项目总览和《项目章程》; +- 初始化消息使用软件领域话术,不出现医疗、临床、注册或 CDO 默认文字。 + +## 4. 工作流 A:software_bootstrap + +### 4.1 定位 + +把一个模糊或历史复杂的软件项目转成可追溯、可决策、可交付的工程基线。默认只运行一次;终止后可重建新实例,但必须保留旧证据。 + +### 4.2 阶段与交付物 + +| 阶段 | 文档任务 | 默认 | 门禁 | +|------|----------|------|------| +| S0 项目边界 | `software_charter` 项目章程 | 必需 | 目标、范围外、用户、成功标准、约束均非空 | +| | `source_inventory` 资料与仓库清单 | existing/self 必需,greenfield 可选 | 来源 hash、权限、时效和排除项完整 | +| S1 现状基线 | `current_state_audit` 现状审计 | existing/self 必需 | confirmed/inferred/unverified 分层;每个 high 问题有证据 | +| | `architecture_baseline` 当前架构与依赖图 | existing/self 必需 | 边界、组件、数据流、部署、外部依赖可追溯 | +| | `software_risk_register` 风险登记册 | 必需 | severity、触发条件、影响、owner、处置和状态齐全 | +| S2 产品基线 | `product_requirements` 产品与系统需求基线 | 必需 | REQ ID 唯一、来源和验收标准齐全 | +| | `scope_backlog` 范围化 backlog | 必需 | 优先级、依赖、验收、非目标和决策项齐全 | +| S3 目标方案 | `target_architecture` 目标架构方案 | 必需 | 对应需求、ADR、迁移路径、失效条件和回滚 | +| | `decision_log` 架构决策记录 | standard/controlled | 每个决策含选项、理由、后果和批准状态 | +| S4 自举路线 | `bootstrap_roadmap` 分阶段建设路线 | 必需 | 每个 wave 有输入、输出、依赖、完成定义和风险 | +| | `verification_strategy` 验证策略与测试矩阵 | 必需 | 单元/集成/UI/安全/恢复与真实 Agent 分开 | +| | `operations_baseline` 部署运维与恢复基线 | standard/controlled | 环境、发布、备份、观测、RPO/RTO 责任明确 | +| | `bootstrap_readiness` 自举就绪评审 | 必需 | 汇总未关闭 blocker,不能把 partial 写成 ready | + +### 4.3 profile 裁剪 + +| profile | 默认文档 | +|---------|----------| +| lean | charter、requirements、backlog、target architecture、roadmap、verification | +| standard | 全部,`decision_log` 和 `operations_baseline` 启用 | +| controlled | 全部,且独立三权、安全审查、审计导出和恢复验证强制 | + +项目类型策略在生成 default plan 时应用,不改 published manifest:例如 greenfield 可关闭 current-state audit,existing/self 不可关闭。 + +### 4.4 阶段推进 + +阶段满足门禁后进入 `awaiting_stage_confirmation`,只发送一次去重通知。创建者可: + +1. 查看文档、风险和下一阶段影响; +2. 确认推进; +3. 留在当前阶段补材料; +4. 对无法继续的实例执行受控终止。 + +系统不得自动进入下一阶段。`bootstrap_readiness` 批准并不意味着全系统生产可用,只意味着已具备进入 `software_delivery` 的可信输入。 + +## 5. 工作流 B:software_delivery + +### 5.1 定位 + +每个里程碑、迭代或发布创建一个新实例。它消费已批准的 bootstrap 产物和上一次 delivery 的复盘,不修改历史基线。 + +### 5.2 阶段与交付物 + +| 阶段 | 文档任务 | 说明 | +|------|----------|------| +| D0 变更定义 | `change_brief` | 目标、范围外、来源需求、风险、成功标准、预算 | +| | `implementation_plan` | 受影响组件、步骤、测试、回滚、文件范围 | +| D1 实施证据 | `change_manifest` | commit/patch、文件 hash、工具、执行者、实际偏差 | +| | `adr_delta` | 仅架构决策变化时启用 | +| D2 验证 | `test_report` | 单元、集成、UI、真实 Agent、失败项和未验证项 | +| | `security_review` | security/privacy/controlled profile 强制 | +| D3 发布 | `release_plan` | 环境、迁移、备份、回滚、观察窗和批准条件 | +| | `release_notes` | 用户可见变化、兼容性、已知限制 | +| D4 学习 | `retrospective` | 目标达成、偏差、事故、经验和行动项 | +| | `backlog_delta` | 新增、关闭、延期及优先级变化 | + +D1 首期允许用户从外部开发流程上传 change manifest;受控工程执行器上线后可自动生成候选证据,但仍须用户批准。 + +### 5.3 交付门禁 + +- change brief 已批准且没有未确认的高影响范围变化; +- implementation plan 的文件范围、测试和回滚明确; +- change manifest 与实际 commit/patch/hash 一致; +- 必需测试通过,失败和跳过项不能隐藏; +- high/critical 风险已关闭或由有权用户明确接受; +- release plan 有回滚和观察窗; +- 发布动作由用户或外部 CI/CD 完成,智能体只提供候选计划和证据。 + +## 6. 智能体小队设计 + +### 6.1 复用策略 + +将“能力角色”和“领域 profile”组合,不复制八套相似角色: + +| 基础角色 | 软件项目用法 | 处理 | +|----------|--------------|------| +| organizer | 材料、源码清单、事实与缺口 | 直接复用,扩充软件字段 | +| searcher | 官方文档、依赖、漏洞和技术资料核验 | 复用,按 network policy 约束 | +| engineer | 架构、代码、数据、部署分析 | 复用内核,加载 `software_engineering` profile | +| writer | 受控技术文档成文 | 复用,移除水木东方/医疗措辞 | +| leader | 任务拆解、终审、待决策汇总 | 改为领域中立 `delivery_lead` profile | +| market | 用户与竞品研究 | 商业产品可选 | +| finance | 成本、云资源、团队工时 | 有预算需求时可选 | +| regulatory | 医疗法规 | 非医疗默认禁用;仅自定义合规 profile 显式启用 | + +新增最小 profile,而不是新增重复的完整角色: + +- `software_product`:产品目标、用户场景、范围和验收; +- `software_architecture`:组件、接口、数据、NFR、ADR 和迁移; +- `software_quality`:测试策略、追溯、缺陷和发布门禁; +- `software_security`:威胁、依赖、权限、数据与 secret; +- `software_operations`:部署、观测、备份、恢复和容量。 + +### 6.2 预设小队 + +**基线审计小队**:organizer → engineer(software_architecture) + searcher → writer → leader。 + +**产品与架构小队**:organizer → software_product + software_architecture(并行)→ writer → leader。 + +**风险与验证小队**:software_quality + software_security(按 profile 条件启用)→ writer → leader。 + +**交付小队**:software_architecture/implementation → software_quality + software_security → operations → leader。 + +### 6.3 任务契约 + +每个步骤必须有结构化契约: + +```text +objective +inputs[](含 authority/hash) +outputs[] +must_cover[] +acceptance[] +forbidden_actions[] +budget +timeout +evidence_required[] +``` + +规划器可建议加步,但新增步骤必须通过角色、工具、预算、目录边界和输出 schema 守卫;不得由模型自由扩大授权。 + +## 7. 软件文档模板与质量门禁 + +### 7.1 模板共同结构 + +所有软件模板至少包含: + +1. 结论与决策请求; +2. 目标、范围和非目标; +3. 输入证据及版本; +4. 正文分析或方案; +5. 风险、影响与依赖; +6. 已确认、推断、未验证清单; +7. 验收标准; +8. 开放问题和责任人; +9. 版本、作者、审核、批准和生成 manifest。 + +### 7.2 确定性门禁 + +| 文档 | 机器门禁示例 | +|------|--------------| +| charter | objective/non-goals/success criteria 非空 | +| source_inventory | 每个来源有类型、revision/hash、权限和排除项 | +| audit | high 问题必须有 evidence、impact、recommendation;未验证不能写 confirmed | +| requirements | ID 唯一;每条有来源、优先级、验收方式 | +| architecture | 组件和接口唯一;每个关键 NFR 有设计响应;Mermaid 安全解析 | +| risk_register | severity/likelihood/impact/owner/mitigation/status 齐全 | +| roadmap | 每个 wave 有依赖、完成定义、验证和回滚 | +| test_report | Input/Expected/Actual/Verdict/Duration;真实与 stub 分开 | +| readiness | 所有 blocker 汇总一致,不得把 partial/fallback 写成 PASS | + +LLM 可以解释事实,但不能降低确定性风险等级、伪造测试结果或把失败改写成成功。 + +## 8. 自举 Agent-System 自身的实战路径 + +推荐按以下顺序使用: + +1. 创建 `existing_self_bootstrap` 项目; +2. 上传/授权读取 `AGENTS.md`、`PROJECT.md`、`.doc` 索引、依赖清单、源码树和当前测试报告; +3. 对话确认本轮目标,例如“建立下一发布周期的可信路线,而不是直接改码”; +4. 真实小队生成项目章程、来源清单、现状审计、架构基线和风险登记册; +5. 用户在页面审核、修改、批准;高风险差异必须确认; +6. 生成目标架构、backlog、自举路线和验证策略; +7. readiness 门禁列出仍开放的 CHAT-INTENT、CI、PI 叙事等问题,不得沿用旧结论冒充当前; +8. 创建者确认 bootstrap 完成; +9. 系统建议创建第一个 `software_delivery` 实例,但不自动创建; +10. 首轮 delivery 仍采用 docs-only:输出 change brief 与 implementation plan,由外部 feature 分支实现; +11. 未来 controlled patch 上线后,再把候选补丁和真实测试证据接回 D1/D2。 + +## 9. 数据模型调整 + +### 9.1 项目与目录 + +建议新增: + +| 对象/字段 | 用途 | +|-----------|------| +| `projects.product_domain` | 权威产品域 | +| `projects.project_type_key` | greenfield/existing/legacy/self-bootstrap | +| `projects.compliance_profile_key` | 合规配置引用 | +| `projects.governance_profile` | lean/standard/controlled | +| `projects.team_mode` | solo/collaborative | +| `projects.execution_mode` | docs_only/read_only_repo/controlled_patch | +| `project_types` | 字段 schema、默认 profile、推荐工作流 | +| `compliance_profiles` | 版本化约束和必需任务 | +| `project_type_workflows` | 允许/推荐工作流及 profile overrides | +| `project_source_bindings` | 资料/仓库来源、revision/hash、权限、secret_ref | +| `agent_profile_versions` | 软件领域角色 overlay 的不可变版本 | + +`device_type/intended_use/target_market` 暂保留兼容读取,但非医疗项目不再以它们作为权威字段。迁移只回填明确数据,不能把所有旧项目自动标记为医疗或软件。 + +### 9.2 工作流适用性 + +统一 `workflow_definitions` 和 manifest 的领域表达: + +```text +applicability = { + product_domains[], + project_types[], + allowed_compliance_profiles[], + governance_profiles[] +} +``` + +删除“仅三正式 key”和固定文档数量的代码硬编码,改为:published + project_selectable + manifest validation + catalog policy。医疗现有三工作流仍保留为正式种子。 + +### 9.3 单人治理 + +在冻结 plan 中加入 `approval_policy`: + +- `independent_three_duties`; +- `creator_acknowledgement`。 + +后者只能用于允许 solo 的项目类型/profile,并在文档与审计中持续显示无独立评审,不复用虚拟用户。 + +## 10. API 设计 + +复用现有 settings/plan/activation/stage API,并新增或扩展: + +```text +GET /api/v1/project-types/catalog +GET /api/v1/compliance-profiles/catalog +POST /api/v1/projects/creation-preview +POST /api/v1/projects # 幂等事务创建 +GET /api/v1/workflows/catalog?product_domain=&project_type=&profile= + +POST /api/v1/projects/{id}/sources +GET /api/v1/projects/{id}/sources +POST /api/v1/projects/{id}/sources/{source}/refresh-preview +POST /api/v1/projects/{id}/sources/{source}/refresh + +GET /api/v1/projects/{id}/settings +GET /api/v1/projects/{id}/workflow-plan/default +PUT /api/v1/projects/{id}/workflow-plan +POST /api/v1/projects/{id}/activation-preview +POST /api/v1/projects/{id}/workflow-instances/activate +POST /api/v1/workflow-instances/{id}/stages/{stage}/advance +``` + +后续受控工程执行: + +```text +POST /api/v1/projects/{id}/change-requests +POST /api/v1/change-requests/{id}/execution-preview +POST /api/v1/change-requests/{id}/approve-execution +POST /api/v1/change-requests/{id}/execute +POST /api/v1/change-requests/{id}/verify +POST /api/v1/change-requests/{id}/merge-preview +``` + +执行、合并和发布分别授权;批准执行不等于批准合并,更不等于批准发布。 + +## 11. UI 融入方案 + +### 11.1 项目创建 + +将现有单页医疗表单改成七步向导,标题改为“创建项目”。根据 product domain 切换字段和帮助文本。右侧固定显示:推荐工作流、预计文档、小队、预算和冻结影响。 + +### 11.2 项目主页 + +新增: + +- 项目类型、治理强度、当前 workflow instance 和 active stage; +- 事实/推断/未验证数量; +- 风险和待决策角标; +- 来源 freshness; +- “建议下一工作流”卡片,仅创建者可确认; +- 当前阶段成员与每份文档职责。 + +### 11.3 文档与对话 + +- 对话输入可触发已冻结的软件 task key; +- 简单问题继续单轮回复,复杂自由任务先给初答并征求是否升级小队; +- 小队名称、角色、步骤、预算和进度在页面可见; +- 右栏复用版本账本、人工修订、变更报告、确认/拒绝和版本比较; +- change report 必须展示项目影响、文档影响、风险、开放问题和分析来源;fallback 继续明确标识。 + +### 11.4 软件领域去污染 + +纯软件项目页面和文档默认不得出现:临床、NMPA、注册检验、GB 9706、器械分类、CDMO、疗效等词。只有用户材料或所选合规 profile 明确要求时才允许出现,并标注来源。 + +## 12. 受控代码执行层(后续) + +### 12.1 安全边界 + +- 仓库路径必须在管理员 allowlist; +- 每次执行创建独立 `feature/` worktree; +- 允许文件范围来自已批准 implementation plan; +- 禁止读取 `.env`、secret、生产 dump; +- 命令来自管理员登记的测试/build allowlist; +- 超时、预算、进程和输出大小有硬上限; +- 失败保留证据并停止,不自动反复重试; +- 任何 merge/push/deploy 都需要新的显式确认。 + +### 12.2 产物 + +- patch/commit 候选; +- 文件变更清单与 hash; +- 命令、退出码、耗时和截断说明; +- 单元/集成/UI 测试报告; +- 风险与回滚; +- 未验证项; +- 与 change brief 和 requirement ID 的追溯。 + +## 13. 实施路线 + +| Wave | 内容 | 主要改动 | 退出标准 | +|------|------|----------|----------| +| W0 契约冻结 | key、profile、阶段、文档、角色、API 与迁移决策 | ADR/manifest schema/错误码 | 评审通过,无双权威 | +| W1 项目域与目录 | 项目类型、合规、治理、catalog filter、迁移 | DB + workflowdef/projectinstance | 医疗旧项目无回归;软件只见兼容工作流 | +| W2 软件工作流与模板 | bootstrap/delivery manifests、模板、executor、quality gate | workflow/squad/template | 校验、模板、任务注册一致 | +| W3 创建事务与向导 | creation preview、幂等创建、成员、模板账本、七步 UI | server + web | 刷新/跨设备一致;不再本地克隆固定 7 文档 | +| W4 对话与小队 | 软件意图词典、domain context、角色 profile、禁医疗污染 | intent/coordinator/bizdev/squad | 简单对话不误启小队,正式任务走冻结实例 | +| W5 门禁与交接 | 软件 readiness、风险、下一 workflow 建议与确认 | projectinstance/notification | 完成后只建议、不自动启动 delivery | +| W6 真实验收 | PG、真实 PI、Ubuntu 无头 UI、重启和权限负例 | tests/reports | 黄金项目全部页面可见且证据落盘 | +| W7 受控工程执行 | repo binding、worktree、patch/test/merge approvals | 独立 Epic | 不直接改保护分支,不泄露 secret | + +建议 W0–W6 作为首个交付,单人全职约 4–6 周;W7 单独估算 2–4 周。实际工期应在 W0 基于代码量和测试环境重新估算。 + +## 14. 验收策略 + +必须分别报告: + +1. 纯函数和 manifest/quality gate 单元测试; +2. PostgreSQL 空库迁移与旧库升级; +3. API 鉴权、并发、幂等、冻结和重启; +4. 前端组件和构建; +5. stub 小队工程回归; +6. 真实 PI Agent Runner 文档生成; +7. Ubuntu Server 官方 Playwright 容器真实 UI; +8. 未来受控代码执行的隔离 worktree 和负例。 + +真实 UI 黄金场景至少包括: + +- 绿地协作项目; +- 既有仓库单人自举项目; +- Agent-System 自身作为项目; +- 无权限成员、错误域工作流、伪造 task key、过期确认令牌; +- 首轮生成、人工修改、审核批准、阶段推进; +- 第二轮差异、风险/影响、确认与拒绝; +- 刷新、重登、应用重启后恢复; +- 纯软件默认无医疗语义污染; +- bootstrap 完成后只出现 delivery 建议,必须由创建者确认。 + +详细用例见 [验收清单](../ops/checklists/2026-09-14-software-project-bootstrap-acceptance.md)。任何未真实运行的用例必须写 `NOT RUN`,不得用 stub 或静态 JSON 冒充。 + +## 15. 风险与对策 + +| 风险 | 等级 | 对策 | +|------|------|------| +| 医疗模板/提示词污染软件结论 | high | 新 task/template/profile;黄金负例扫描 | +| 工作流 key 和 executor 继续硬编码 | high | 统一 catalog policy 和 registry,发布时完整校验 | +| 单人模式伪造三权 | high | creator acknowledgement + 明示未独立评审 | +| 自举 Agent 越权改自身治理 | critical | 首期只读;后续 worktree + 多段批准 | +| 仓库和 secret 泄露到 prompt | critical | allowlist、排除、secret_ref、输出扫描 | +| 文档很多但不能指导执行 | medium | requirement/backlog/roadmap/test trace;delivery 实例承接 | +| 自由任务绕过正式工作流 | high | 正式交付只认 doc_task_instance;ad-hoc 只能辅助 | +| 旧医疗项目回归 | high | 新 key/新版本;兼容迁移;医疗/软件双黄金 E2E | +| 真实 PI 产出幻觉 | high | 证据层级、确定性门禁、用户审批、不得伪造测试 | +| 大型仓库上下文爆炸 | medium | 清单→相关文件→摘要的分层采集;预算和 hash | + +## 16. 决策请求 + +实施前只需要用户确认两项产品决策: + +1. 首期是否按推荐的 `docs_only/read_only_repo` 交付,把自动生成代码补丁放到 W7; +2. 当前实际使用是 `solo` 还是 `collaborative`,以冻结真实的审批策略。 + +其余字段可采用本文件推荐默认值并在创建向导中调整。 + +## 17. 关联证据 + +- [现状调研](../ops/research/2026-09-14-software-project-bootstrap-current-state.md) +- [实施 backlog](../ops/long-term/2026-09-14-software-project-bootstrap-implementation.md) +- [验收清单](../ops/checklists/2026-09-14-software-project-bootstrap-acceptance.md) +- [工作流运行时权威 ADR](../adr/2026-09-12-workflow-runtime-authority.md) +- [生产级工作流治理方案](../remediation/2026-09-11-production-ready-workflow-governance-plan.md) +- [文档运行时真实 UI 报告](../test-reports/2026-09-14-document-revision-runtime-ui-test-report.md) diff --git a/.doc/system-design/README.md b/.doc/system-design/README.md index 9b665cda..651ea9c6 100644 --- a/.doc/system-design/README.md +++ b/.doc/system-design/README.md @@ -12,7 +12,6 @@ | 项 | 链接 | |-----|------| | 主报告 | [intent-recognition/01-意图识别框架-设计-架构-实现-难点-解决方案-亮点与优势.md](intent-recognition/01-意图识别框架-设计-架构-实现-难点-解决方案-亮点与优势.md) | -| 中间分析 | [.tmp/intent-recognition/](../.tmp/intent-recognition/) | | 一句话总结 | 纯规则 + 四级漏斗 + 三分支消解的 L1 协作对话层 | **核心要点**: @@ -31,7 +30,6 @@ | 项 | 链接 | |-----|------| | 主报告 | [agent-squad/02-智能体小队编排-设计-思路-架构-实现-难点-解决方案-亮点与优势.md](agent-squad/02-智能体小队编排-设计-思路-架构-实现-难点-解决方案-亮点与优势.md) | -| 中间分析 | [.tmp/agent-squad/](../.tmp/agent-squad/) | | 一句话总结 | 角色-任务-工作区-黑板四元模型 + 沙箱化执行 + 动态工作流 + 三层质量门禁 | **核心要点**: @@ -84,6 +82,23 @@ --- +### 5. 纯软件项目自举工作流 + +| 项 | 链接 | +|-----|------| +| 主报告 | [2026-09-14-software-project-bootstrap-workflow.md](2026-09-14-software-project-bootstrap-workflow.md) | +| 一句话总结 | 一次性 Bootstrap 建立可信基线,可重复 Delivery 承接迭代;复用治理引擎,隔离医疗语义和代码执行权限 | + +**核心要点**: + +- 七步项目创建向导,分离 product domain、project type、compliance、governance 和 execution mode; +- `software_bootstrap` 与 `software_delivery` 两条工作流串联,创建者确认推进; +- 复用通用智能体角色和小队治理,通过软件领域 profile 增强; +- 单人模式不伪造三权,持续标记“未独立评审”; +- 首期 docs-only/read-only,后续代码执行必须隔离 worktree 并分段审批。 + +--- + ## 🏗️ 在整体架构中的位置 ``` @@ -168,6 +183,6 @@ ## 🔗 相关资源 -- 架构总览:[.doc/system-design/architecture-design.md](../architecture-design.md)(已有的项目骨架设计文档) +- 架构总览:[.doc/system-design/architecture-design.md](architecture-design.md)(已有的项目骨架设计文档) - 测试报告:[.doc/test-reports/](../test-reports/)(多轮多角色端到端测试报告) - 历史功能设计:[.doc/archive/design/superpowers/](../archive/design/superpowers/)