Capability Workbench

当前仓库是轻量架构脚手架，不是细粒度开发流程引擎。边界说明见 docs/SCAFFOLD_BOUNDARY.md。

这是一个给“你 + Codex”使用的架构设计工作台。

它的重点不是多 Agent 治理，也不是先做一个大平台，而是让架构设计先稳定落到仓库里，并让当前对话和未来新对话都能沿同一套能力、组件、词汇模型继续工作。

主目标

• 用 capability 表达系统能做什么
• 用 component 表达能力如何被转换出来
• 用 workflow_network 表达岗位、流转关系和触发条件组成的依赖驱动工作网络
• 用 requirement_package 表达一轮足以支持全局架构设计的需求包
• 用 component_local_view 表达封装组件内部的局部能力-组件架构图
• 用 requirement 按条承载当前要处理的需求
• 用 constraint 表达对能力和组件边界的收紧条件
• 用 source_document 和 source_block 追踪原始文档及其拆分来源
• 用 term 稳定能力与组件的描述语言
• 用 term_refs 显式记录正式对象实际复用的词汇
• 所有 content 字段名都必须由 term 治理
• term 必须至少承担一种正式用途：field_label 或 content_text
• 只有 usage_modes 包含 content_text 的 term 才允许进入自然语言正文的链接标注
• 用 content_term_annotations 给正文中的已治理词汇增加独立标注层，而不把链接语法直接塞进正文
• 用 term_usage_modes.py 汇总词汇表里哪些 term 只用于字段名，哪些还能进入正文
• 用 term_annotation_coverage.py 检查指定范围内正文里的已治理词汇出现是否都已成功标注
• 用小脚本逐步自举这套设计环境

当前核心文件

• AGENTS.md
  • 给未来新对话的 Codex 的工作规则
• C:\Users\23779\.codex\skills\product-manager-cw\SKILL.md
  • 产品经理角色入口
• C:\Users\23779\.codex\skills\global-architect-cw\SKILL.md
  • 全局架构师角色入口
• C:\Users\23779\.codex\skills\wrapped-component-owner-cw\SKILL.md
  • 复合组件负责人角色入口
• C:\Users\23779\.codex\skills\advance-work-unit-cw\SKILL.md
  • 局部工作单元推进入口
• C:\Users\23779\.codex\skills\verify-work-unit-cw\SKILL.md
  • 测试者角色入口
• docs/ARCHITECTURE_MODEL.md
  • 能力、组件、词汇模型的简明方法说明
• architecture/
  • 正式架构对象
• tools/
  • 围绕这套对象模型工作的脚本

目录结构

architecture/
  capabilities/
    foundation/
    approved/
  components/
    approved/
  requirement_packages/
    draft/
    approved/
  workflow_networks/
    approved/
  requirements/
    draft/
    approved/
  constraints/
    draft/
    approved/
  source_documents/
    draft/
    approved/
  source_blocks/
    draft/
    approved/
  decomposition_views/
  component_local_views/
  terms/
    approved/
  requirement_capability_sets/
    draft/
    approved/
  governance/
docs/
templates/
tools/
workflow/

workflow/ 目前保留，但不是当前阶段的主线。

推荐工作顺序

1. 先把需求改写成能力问题
2. 再判断哪些词汇可复用，哪些词汇要新增
   • 字段名一律复用已治理 term
   • 自然语言正文里的词只有在足够原创、值得进入词汇表时才新增 term
   • 新增或修改正式语义对象后，再检查一次 term_reference_coverage.py
   • 若正文里复用了已治理词汇，再检查一次 term_annotation_coverage.py
3. 再把能力拆成组件输入输出
4. 再决定脚本和实现文件
5. 最后运行校验

AI 推进局部工作单元的默认顺序

当新对话里的 Codex 需要推进某个 decomposition view 中的局部工作时，默认先按这个顺序检查：

python tools/decomposition_view.py progress <view_id>
python tools/decomposition_view.py verification <view_id>
python tools/parallel_worksets.py <view_id>

然后再决定进入：

• component_context.py <component_id> -> 组件开发
• adapter_context.py <adapter_id> -> adapter 开发
• bridge_escalations.py list -> 适配失败后的转接升级路径

如果当前工作发生在某个 wrapped component 的 component_local_view 内部，默认顺序是：

python tools/component_local_view.py verification <view_id>
python tools/component_local_parallel_worksets.py <view_id>

然后再决定进入：

• component_context.py <component_id> -> 内部子组件开发
• component_verification.py set <component_id> ... -> 内部子组件测试推进

如果当前角色是测试者，默认顺序是：

python tools/decomposition_view.py verification <view_id>
python tools/component_local_view.py verification <view_id>
python tools/component_verification.py show
python tools/component_verification.py set <component_id> in_test --note "..."
python tools/component_verification.py set <component_id> passed --note "..."

或在失败时：

python tools/component_verification.py set <component_id> failed --note "..."

常用命令

python tools/validate.py
python tools/component_progress.py show
python tools/component_progress.py set <component_id> <progress> --note "..."
python tools/component_verification.py show
python tools/component_verification.py set <component_id> <status> --note "..."
python tools/component_sync.py status
python tools/component_sync.py ack <component_id>
python tools/component_context.py <component_id>
python tools/component_context.py <component_id> --write
python tools/component_context.py --view <view_id>
python tools/component_context.py --view <view_id> --write
python tools/parallel_worksets.py <view_id>
python tools/parallel_worksets.py <view_id> --write
python tools/adapter_context.py <adapter_id>
python tools/adapter_context.py <adapter_id> --write
python tools/adapter_gaps.py
python tools/adapter_gaps.py --all
python tools/locate_components.py <path> [<path> ...]
python tools/decomposition_view.py list
python tools/decomposition_view.py show <view_id>
python tools/decomposition_view.py create <view_id> --root <capability_id>
python tools/decomposition_view.py gaps <view_id>
python tools/decomposition_view.py progress <view_id>
python tools/decomposition_view.py verification <view_id>
python tools/decomposition_view.py backlog <view_id>
python tools/decomposition_view.py sync <view_id>
python tools/component_local_view.py list
python tools/component_local_view.py show <view_id>
python tools/component_local_view.py create <view_id> --component <component_id>
python tools/component_local_view.py add-node <view_id> <component_id> <depth> --output <capability_id>
python tools/component_local_view.py validate <view_id>
python tools/component_local_view.py verification <view_id>
python tools/component_local_view.py mermaid <view_id>
python tools/component_local_parallel_worksets.py <view_id>
python tools/component_local_parallel_worksets.py <view_id> --write
python tools/bridge_escalations.py list
python tools/bridge_escalations.py show <bridge_escalation_id>
python tools/workflow_network.py list
python tools/workflow_network.py show <workflow_network_id>
python tools/workflow_network.py mermaid <workflow_network_id> --write
python tools/workflow_role_context.py <workflow_network_id> <role_id>
python tools/workflow_role_context.py <workflow_network_id> <role_id> --write
python tools/workflow_role_context.py <workflow_network_id> role_wrapped_component_owner --component-local-view <view_id>
python tools/global_architecture_context.py <requirement_package_id>
python tools/global_architecture_context.py <requirement_package_id> --write
python tools/region_search.py inspect <component_id> --hops 1
python tools/region_search.py search --max-hops 2 --min-components 4 --min-internal-links 4 --max-boundary-ratio 0.5 --max-gateway-ratio 0.5
python tools/region_search.py mermaid <component_id> --hops 1 --write
python tools/requirements.py list
python tools/requirement_capability_sets.py list
python tools/requirement_capability_sets.py show <requirement_capability_set_id>
python tools/requirement_packages.py list
python tools/requirement_packages.py show <requirement_package_id>
python tools/requirement_package_readiness.py list
python tools/requirement_package_readiness.py show <requirement_package_id>
python tools/requirement_package_readiness.py show <requirement_package_id> --write
python tools/requirement_package_decomposition_starts.py list
python tools/requirement_package_decomposition_starts.py show <requirement_package_id>
python tools/requirement_package_decomposition_starts.py show <requirement_package_id> --write
python tools/requirements.py show <requirement_id>
python tools/constraints.py list
python tools/constraints.py show <constraint_id>
python tools/source_materials.py documents
python tools/source_materials.py document <source_document_id>
python tools/source_materials.py blocks
python tools/source_materials.py block <source_block_id>
python tools/query.py capability "读取文件"
python tools/query.py term "约束"
python tools/query.py term "接口" --usage-mode content_text
python tools/query.py term "名称" --usage-mode field_label
python tools/term_usage_modes.py summary
python tools/term_usage_modes.py content-text
python tools/term_usage_modes.py object <term_id>
python tools/term_reference_coverage.py summary
python tools/term_reference_coverage.py missing
python tools/term_reference_coverage.py object <object_id>
python tools/term_annotation_coverage.py summary
python tools/term_annotation_coverage.py missing
python tools/term_annotation_coverage.py object <object_id>
python tools/term_annotation_coverage.py path architecture/components
python tools/query.py paths <capability_id>
python tools/impact.py <object_id>
python tools/scaffold.py capability <capability_id>
python tools/scaffold.py component <component_id> --owner agent_tbd
python tools/scaffold.py adapter <adapter_id> --owner agent_tbd
python tools/scaffold.py component-local-view <view_id> --component <component_id>
python tools/scaffold.py bridge-escalation <bridge_escalation_id> --owner agent_tbd
python tools/scaffold.py term <term_id> --owner agent_tbd
python tools/scaffold.py requirement-capability-set <requirement_capability_set_id> --owner agent_tbd
python tools/scaffold.py source-document <source_document_id>
python tools/scaffold.py source-block <source_block_id> --source-document <source_document_id>
python tools/bootstrap_context.py
python tools/bootstrap_context.py --write

这版已经具备的能力

• 把能力、组件、词汇落成仓库对象
• 校验结构一致性和词汇治理约束
• 读取和更新组件开发进度
• 通过显式同步基线判断组件代码和架构是否已经失步
• 为单个组件生成可直接交给 Codex 的局部实现上下文
• 按需求分解视图批量导出多个组件的实现上下文包
• 为单个 adapter 生成可直接交给 Codex 的局部实现上下文
• 分析哪些组件连接已经有 adapter，哪些仍然裸连
• 根据代码路径反查命中的组件 implementation_scope
• 读取和查看逐条需求对象，并把需求与目标 capability / decomposition view 关联
• 读取和查看需求能力集合对象，把一轮需求包中的 requirement 整理为目标能力、依赖能力和分解起点集合
• 读取和查看需求包对象，把一批 requirement / constraint 整理成全局架构师的一轮设计输入
• 读取和查看逐条约束对象，并把约束连接到 capability、component 与 requirement
• 读取和查看源文档对象、源块对象，并显式记录 requirement / constraint / term 的来源追踪
• 读取、创建和校验需求分解视图
• 为某个封装组件维护内部能力-组件架构视图，并导出 mermaid 图给组件开发者查看
• 读取、查看和导出工作流网络对象，把岗位协作网络正式落成仓库对象
• 按组件连接拓扑搜索内部连接密、边界连接少且关隘集中的局部区域，供架构师手工判断是否值得封装
• 分析需求分解视图中的能力缺口和依赖闭合状态
• 评估需求分解视图中各组件能力转换关系的落实进度
• 从需求分解视图中提取下一轮待补 capability 列表
• 分析对象的下游影响传播
• 检索能力候选项和词汇候选项
• 汇总正式对象的显式词汇引用覆盖，并暴露缺失 term_refs 或孤立 term
• 汇总正文中可识别的治理词汇出现与 content_term_annotations 之间的覆盖缺口
• 追踪能力组合路径
• 生成新对象骨架
• 生成供新对话读取的上下文摘要

当前不优先做的内容

• 多 Agent 互动流程
• 投票机制细化
• 提案流转自动化
• UI 平台
• 语义真值自动判断

这版的目标很克制：先让架构设计模型自己站住，再逐步长出下一批工具。