@pzy560117/codex-harness 0.1.3 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/design/screen-states.md

@@ -1,122 +1,157 @@
-# Screen States 模板
-
-> 目标: 把每个页面状态写成可实现、可做 story、可做 visual regression 的状态规格。
-
-## 页面名称
-
-- Page ID:
-- 页面:
-- 路由/入口:
-- 角色:
-- 关联需求:
-- 关联设计稿:
-
-## 状态清单
-
-### default
-
-- 触发条件:
-- 数据条件:
-- 页面表现:
-- 用户可执行动作:
-- 组件影响:
-- story 名称:
-- visual baseline:
-
-### empty
-
-- 触发条件:
-- 数据条件:
-- 页面表现:
-- 用户可执行动作:
-- 恢复路径:
-- story 名称:
-- visual baseline:
-
-### loading
-
-- 触发条件:
-- 等待对象:
-- 页面表现:
-- 用户可执行动作:
-- 超时后行为:
-- story 名称:
-- visual baseline:
-
-### error
-
-- 触发条件:
-- 错误类型:
-- 页面表现:
-- 用户可执行动作:
-- 重试 / 兜底:
-- story 名称:
-- visual baseline:
-
-### permission_denied
-
-- 触发条件:
-- 权限规则:
-- 页面表现:
-- 用户可执行动作:
-- 是否隐藏受限操作:
-- story 名称:
-- visual baseline:
-
-### disabled
-
-- 触发条件:
-- 禁用对象:
-- 禁用原因展示:
-- 用户可执行动作:
-- 恢复条件:
-- story 名称:
-- visual baseline:
-
-### long_content
-
-- 触发条件:
-- 极端数据:
-- 页面表现:
-- 用户可执行动作:
-- 截断 / 换行 / tooltip 规则:
-- story 名称:
-- visual baseline:
-
-### responsive/mobile
-
-- 触发条件:
-- 断点:
-- 页面表现:
-- 用户可执行动作:
-- 折叠策略:
-- 表格 / 列表替代形态:
-- 主操作可达性:
-- 触控目标:
-- 长文本 / 长标签处理:
-- story 名称:
-- visual baseline:
-
-### motion/reduced_motion
-
-- 触发条件:
-- 默认动效:
-- reduced motion 表现:
-- 用户可执行动作:
-- 组件影响:
-- story 名称:
-- visual baseline:
-
-## 状态到测试映射
-
-| 状态 | Story | Interaction Test | E2E | Visual |
-| --- | --- | --- | --- | --- |
-| default | | | | |
-| empty | | | | |
-| loading | | | | |
-| error | | | | |
-| permission_denied | | | | |
-| disabled | | | | |
-| long_content | | | | |
-| mobile | | | | |
-| reduced_motion | | | | |
+# Screen States 模板
+
+> 目标: 把每个页面状态写成可实现、可做 story、可做 visual regression 的状态规格。
+
+## 页面名称
+
+- Page ID:
+- 页面:
+- 路由/入口:
+- 角色:
+- 关联需求:
+- 关联设计稿:
+
+## 状态清单
+
+### default
+
+- 触发条件:
+- 数据条件:
+- 页面表现:
+- 用户可执行动作:
+- 组件影响:
+- story 名称:
+- visual baseline:
+
+### empty
+
+- 触发条件:
+- 数据条件:
+- 页面表现:
+- 用户可执行动作:
+- 恢复路径:
+- story 名称:
+- visual baseline:
+
+### loading
+
+- 触发条件:
+- 等待对象:
+- 页面表现:
+- 用户可执行动作:
+- 超时后行为:
+- story 名称:
+- visual baseline:
+
+### error
+
+- 触发条件:
+- 错误类型:
+- 页面表现:
+- 用户可执行动作:
+- 重试 / 兜底:
+- story 名称:
+- visual baseline:
+
+### submitting
+
+- 触发条件:
+- 提交对象:
+- 页面表现:
+- 用户可执行动作:
+- 防重复提交策略:
+- story 名称:
+- visual baseline:
+
+### retry
+
+- 触发条件:
+- 失败来源:
+- 页面表现:
+- 用户可执行动作:
+- 重试限制 / 节流:
+- story 名称:
+- visual baseline:
+
+### offline
+
+- 触发条件:
+- 网络条件:
+- 页面表现:
+- 用户可执行动作:
+- 恢复后行为:
+- story 名称:
+- visual baseline:
+
+### permission_denied
+
+- 触发条件:
+- 权限规则:
+- 页面表现:
+- 用户可执行动作:
+- 是否隐藏受限操作:
+- story 名称:
+- visual baseline:
+
+### disabled
+
+- 触发条件:
+- 禁用对象:
+- 禁用原因展示:
+- 用户可执行动作:
+- 恢复条件:
+- story 名称:
+- visual baseline:
+
+### long_content
+
+- 触发条件:
+- 极端数据:
+- 页面表现:
+- 用户可执行动作:
+- 截断 / 换行 / tooltip 规则:
+- story 名称:
+- visual baseline:
+
+### responsive/mobile
+
+- 触发条件:
+- 断点:
+- 页面表现:
+- 用户可执行动作:
+- 折叠策略:
+- 表格 / 列表替代形态:
+- 主操作可达性:
+- 触控目标:
+- 安全区策略:
+- 键盘遮挡处理:
+- 长文本 / 长标签处理:
+- story 名称:
+- visual baseline:
+
+### motion/reduced_motion
+
+- 触发条件:
+- 默认动效:
+- reduced motion 表现:
+- 用户可执行动作:
+- 组件影响:
+- story 名称:
+- visual baseline:
+
+## 状态到测试映射
+
+| 状态 | Story | Interaction Test | E2E | Visual |
+| --- | --- | --- | --- | --- |
+| default | | | | |
+| empty | | | | |
+| loading | | | | |
+| error | | | | |
+| submitting | | | | |
+| retry | | | | |
+| offline | | | | |
+| permission_denied | | | | |
+| disabled | | | | |
+| long_content | | | | |
+| mobile | | | | |
+| reduced_motion | | | | |

package/package-source/docs/codex-harness-engineering/templates/design/visual-parity-review.md

@@ -41,13 +41,13 @@ artifacts/visual-review/<feature>/<page>/
 | --- | --- | --- | --- | --- | --- | --- |
 | | default | Desktop 1440x900 | | | | Yes |
 | | empty | Desktop 1440x900 | | | | Yes / N/A |
-| | loading | Desktop 1440x900 | | | | Yes / N/A |
-| | error | Desktop 1440x900 | | | | Yes / N/A |
-| | permission | Desktop 1440x900 | | | | Yes / N/A |
-| | long_content | Desktop 1440x900 | | | | Yes / N/A |
-| | default | Tablet 768x1024 | | | | Yes / N/A |
-| | default | Mobile 375x812 | | | | Yes / N/A |
-| | reduced_motion | Desktop 1440x900 | | | | Yes / N/A |
+| | loading | Desktop 1440x900 | | | | Yes / N/A |
+| | error | Desktop 1440x900 | | | | Yes / N/A |
+| | permission | Desktop 1440x900 | | | | Yes / N/A |
+| | long_content | Desktop 1440x900 | | | | Yes / N/A |
+| | default | Tablet 768x1024 | | | | Yes / N/A |
+| | default | Mobile 375x812 | | | | Yes / N/A |
+| | reduced_motion | Desktop 1440x900 | | | | Yes / N/A |
 
 ## 5. 浏览器截图命令示例
 
@@ -77,11 +77,11 @@ npx playwright screenshot --viewport-size=1440,900 "$env:VISUAL_BASE_URL/pets" "
 - 字体、字号、字重、行高、间距、圆角、阴影、边框、颜色是否明显偏离。
 - 商品图、图标、按钮、标签、价格、状态文本等业务元素是否缺失或多出。
 - 空态、加载态、错误态、移动端状态是否符合设计图和 screen-states。
-- 是否有文字溢出、遮挡、错位、重叠、响应式破版。
-- 动效、reduced motion、focus、hover、disabled 是否符合规格或有截图 / 录像证据。
-- 移动端触控目标、折叠策略、表格替代形态是否符合 screen-states 和 frontend architecture。
-
-输出：
+- 是否有文字溢出、遮挡、错位、重叠、响应式破版。
+- 动效、reduced motion、focus、hover、disabled 是否符合规格或有截图 / 录像证据。
+- 移动端触控目标、折叠策略、表格替代形态是否符合 screen-states 和 frontend architecture。
+
+输出：
 - Verdict: PASS / FAIL
 - 主要差异清单
 - 必须修复项
@@ -96,11 +96,11 @@ npx playwright screenshot --viewport-size=1440,900 "$env:VISUAL_BASE_URL/pets" "
 | 字体与字号 | | | PASS / FAIL | |
 | 间距与密度 | | | PASS / FAIL | |
 | 颜色与状态色 | | | PASS / FAIL | |
-| 组件圆角 / 阴影 / 边框 | | | PASS / FAIL | |
-| 业务元素完整性 | | | PASS / FAIL | |
-| 响应式 | | | PASS / FAIL / N/A | |
-| 动效 / reduced motion | | | PASS / FAIL / N/A | |
-| 可访问性可见状态 | | | PASS / FAIL / N/A | |
+| 组件圆角 / 阴影 / 边框 | | | PASS / FAIL | |
+| 业务元素完整性 | | | PASS / FAIL | |
+| 响应式 | | | PASS / FAIL / N/A | |
+| 动效 / reduced motion | | | PASS / FAIL / N/A | |
+| 可访问性可见状态 | | | PASS / FAIL / N/A | |
 
 ## 8. 失败处理
 
@@ -115,10 +115,10 @@ npx playwright screenshot --viewport-size=1440,900 "$env:VISUAL_BASE_URL/pets" "
 ## 9. 通过标准
 
 - [ ] 每个 required UI state 都有参考图或明确豁免。
-- [ ] 每个 required UI state 都有真实浏览器截图。
-- [ ] mobile required viewport 有真实浏览器截图或明确豁免。
-- [ ] 可访问性、focus、reduced motion 的可见状态已有截图、录像或报告证据。
-- [ ] 截图 viewport、测试数据和页面状态与参考图一致。
+- [ ] 每个 required UI state 都有真实浏览器截图。
+- [ ] mobile required viewport 有真实浏览器截图或明确豁免。
+- [ ] 可访问性、focus、reduced motion 的可见状态已有截图、录像或报告证据。
+- [ ] 截图 viewport、测试数据和页面状态与参考图一致。
 - [ ] 图片对比报告存在，并给出 `Verdict: PASS`。
 - [ ] 所有 FAIL 差异都已修复并重新截图。
 - [ ] Stage 1 Review 能读取参考图路径、实拍图路径和对比报告。

package/package-source/docs/codex-harness-engineering/templates/docs/AGENTS.md

@@ -0,0 +1,19 @@
+# AGENTS.md
+
+## 目录作用
+
+- 存放会复制到项目 `docs/harness/` 的方法论文档模板和使用说明。
+
+## 结构索引
+
+- `harness-architecture.md`：分层架构。
+- `rule-governance.md`：规则治理。
+- `task-session-strategy.md`：会话与任务策略。
+- `new-project-usage.md`：新项目接入和使用。
+- `frontend-quality-rules.md` / `directory-structure-template.md` / `code-style-and-naming.md`：前端、目录、命名规则。
+- `service-dependency-matrix.md` / `architecture-constraints.md` / `env-and-deployment-template.md`：高风险 truth source 模板。
+
+## 修改规则
+
+- 这里放的是“安装后项目要读的深文档模板”，不是仓库根 README 的重复。
+- 如果规则已变成脚本 / lint / hook 可检查项，文档应解释用途和分层，而不是重复堆命令细节。

package/package-source/docs/codex-harness-engineering/templates/docs/architecture-constraints.md

@@ -1,83 +1,97 @@
-# Architecture Constraints Packet
-
-本文件在需求分析结束、进入计划或编码前完成。它把“系统应该是什么形态”转成可执行约束，供 `task.json`、Stage 1 Review 和验证命令使用。
-
-默认路径是 `docs/architecture/constraints.md`。项目可以在 `task.json.runtime.handoff.truth_sources.architecture` 中改用其他路径，但后续任务、prompt 和 review 必须读取同一组 truth source。
-
-## 1. System Shape
-
-- `delivery_shape`: `web_app` / `backend_service` / `monolith` / `frontend_app` / `cli` / `library` / `automation` / `data_pipeline` / `domain_prototype` / `other:<name>`
-- `runtime_model`: `http_service` / `worker` / `scheduled_job` / `static_site` / `embedded_library` / `command` / `not_applicable`
-- `deployment_unit`: `container` / `single_process` / `serverless` / `package` / `static_assets` / `not_applicable`
-- `production_entrypoints`: 列出当前项目真实启动入口、公开命令、页面入口、worker entry、package export、Dockerfile 或 `not_applicable`。
-
-## 2. Public Interface Boundary
-
-- `public_interfaces`: `HTTP` / `gRPC` / `GraphQL` / `MQ` / `CLI` / `UI route` / `package API` / `file format` / `none`
-- `contract_source`: `OpenAPI` / `protobuf` / `GraphQL schema` / `existing API` / `typed API` / `docs` / `not_applicable`
-- `interface_trace_rule`: 每个公开入口应能追踪到实现、测试和证据路径；没有公开入口时写明 `not_applicable`。
-
-## 2.1 Service And Contract Topology
-
-多服务、多仓库、契约或外部系统项目必须声明服务拓扑；不适用时写明 `service_matrix: not_applicable`。
-
-- `service_matrix`: `.service-matrix/dependencies.yaml` / `not_applicable` / `project_defined:<path>`
-- `affected_services`: 本轮需求会修改或影响的服务、应用、包、worker、前端入口或外部系统。
-- `upstream_downstream_rule`: 说明上游调用方和下游依赖方如何确认；不能只依赖代码搜索。
-- `contract_branch_rule`: IDL、OpenAPI、schema、generated code 或外部契约是否需要同分支、同版本或兼容性证明。
-- `change_gate_rule`: 对应 contract diff、consumer test、integration test、mock 更新、灰度或回滚检查。
-
-## 3. Data Boundary
-
-- `persistence_boundary`: `MySQL` / `PostgreSQL` / `SQLite` / `Redis` / `object_storage` / `filesystem` / `browser_storage` / `external API` / `none`
-- `schema_or_migration_required`: `yes` / `no` / `not_applicable`
-- `repository_policy`: 说明声明交付路径使用的真实数据边界；测试替身、fixture、mock adapter 或 local-only adapter 只能用于声明允许的范围。
-- `consistency_requirements`: 事务、锁、幂等键、唯一约束、审计保留、缓存失效、离线同步或 `not_applicable`。
-
-## 4. Async And Worker Boundary
-
-- `async_required`: `yes` / `no`
-- `scheduling_model`: `DB polling` / `MQ consumer` / `cron` / `event bus` / `browser event` / `manual command` / `none`
-- `concurrency_control`: `DB row lock` / `optimistic CAS` / `distributed lock` / `single process` / `browser single-thread` / `none`
-- `time_source`: `database time` / `server time` / `event time` / `browser time` / `not_applicable`
-
-## 5. Test Double Policy
-
-- `test_double_allowed_scope`: `unit_tests_only` / `contract_tests` / `local_demo` / `domain_prototype` / `not_allowed` / `project_defined:<rule>`
-- `mock_as_acceptance_evidence`: `no` by default；如果允许，必须写明原因、适用依赖、过期条件和替代真实验证计划。
-- `minimum_integration_evidence`: 列出当前项目最低真实验证组合，例如 UI + API、API + DB、CLI + filesystem、package API + consumer test、worker + queue，或 `not_applicable`。
-
-## 6. Forbidden Implementations
-
-按项目填充，不要只写抽象原则。示例只作为选项，不代表所有项目都适用：
-
-- 不允许只实现领域 service 而没有任务声明的公开入口。
-- 不允许公开契约有 operation 但代码没有对应实现或验证。
-- 不允许用测试替身、mock、fixture、local-only adapter 冒充声明交付路径。
-- 不允许把 `domain_prototype` 标记为可交付功能完成。
-- 不允许只运行 `git diff --check` 就声明 `feature_impl` 完成。
-
-## 7. Architecture Fitness Checks
-
-每个项目至少定义一个可运行或可审查的架构适配检查，并把命令或检查项同步到 `task.json` 的 `test_command`。
-
-```powershell
-<replace-with-project-fitness-check>
-```
-
-若暂时没有脚本，必须在 `docs/testing/verify-matrix.md` 写明等价检查项。可选检查包括：
-
-- 声明的生产入口存在，且能被启动、导入、访问或执行。
-- 公开接口与实现、测试和证据路径可追踪。
-- 声明交付路径未引用禁止的测试替身。
-- 需要持久化、worker、浏览器、文件或第三方服务时，存在对应的真实验证证据。
-- 不适用的边界已明确标记为 `not_applicable`，而不是留空。
-
-## 8. Definition Of Done
-
-- `architecture_constraints` 已从本文件或等价 truth source 复制到每个相关 `feature_impl` 任务。
-- 多服务、多仓库或契约任务已把服务矩阵、受影响服务和 change gates 复制到相关 `feature_impl` 的 `context_files`、`architecture_constraints`、`qa_contract` 和 `test_command`。
-- `forbidden_implementations` 已覆盖当前项目最容易跑偏的替代实现。
-- `test_command` 包含项目适配检查、affected tests、必要契约/集成/端到端验证和 `git diff --check`。
-- Stage 1 Review 对声明的架构形态给出 PASS。
-- 完成声明能说明声明交付路径、测试替身和不适用边界。
+# Architecture Constraints Packet
+
+本文件在需求分析结束、进入计划或编码前完成。它把“系统应该是什么形态”转成可执行约束，供 `task.json`、Stage 1 Review 和验证命令使用。
+
+默认路径是 `docs/architecture/constraints.md`。项目可以在 `task.json.runtime.handoff.truth_sources.architecture` 中改用其他路径，但后续任务、prompt 和 review 必须读取同一组 truth source。
+
+## 1. System Shape
+
+- `delivery_shape`: `web_app` / `backend_service` / `monolith` / `frontend_app` / `cli` / `library` / `automation` / `data_pipeline` / `domain_prototype` / `other:<name>`
+- `runtime_model`: `http_service` / `worker` / `scheduled_job` / `static_site` / `embedded_library` / `command` / `not_applicable`
+- `deployment_unit`: `container` / `single_process` / `serverless` / `package` / `static_assets` / `not_applicable`
+- `production_entrypoints`: 列出当前项目真实启动入口、公开命令、页面入口、worker entry、package export、Dockerfile 或 `not_applicable`。
+
+## 2. Public Interface Boundary
+
+- `public_interfaces`: `HTTP` / `gRPC` / `GraphQL` / `MQ` / `CLI` / `UI route` / `package API` / `file format` / `none`
+- `contract_source`: `OpenAPI` / `protobuf` / `GraphQL schema` / `existing API` / `typed API` / `docs` / `not_applicable`
+- `interface_trace_rule`: 每个公开入口应能追踪到实现、测试和证据路径；没有公开入口时写明 `not_applicable`。
+
+## 2.1 Service And Contract Topology
+
+多服务、多仓库、契约或外部系统项目必须声明服务拓扑；不适用时写明 `service_matrix: not_applicable`。
+
+- `service_matrix`: `.service-matrix/dependencies.yaml` / `not_applicable` / `project_defined:<path>`
+- `affected_services`: 本轮需求会修改或影响的服务、应用、包、worker、前端入口或外部系统。
+- `upstream_downstream_rule`: 说明上游调用方和下游依赖方如何确认；不能只依赖代码搜索。
+- `contract_branch_rule`: IDL、OpenAPI、schema、generated code 或外部契约是否需要同分支、同版本或兼容性证明。
+- `change_gate_rule`: 对应 contract diff、consumer test、integration test、mock 更新、灰度或回滚检查。
+
+## 3. Data Boundary
+
+- `persistence_boundary`: `MySQL` / `PostgreSQL` / `SQLite` / `Redis` / `object_storage` / `filesystem` / `browser_storage` / `external API` / `none`
+- `schema_or_migration_required`: `yes` / `no` / `not_applicable`
+- `historical_data_strategy`: 旧数据如何兼容、回填、默认值和发布窗口；不适用写 `not_applicable`
+- `migration_rollback_strategy`: migration 如何回滚、降级或 feature flag 切换；不适用写 `not_applicable`
+- `repository_policy`: 说明声明交付路径使用的真实数据边界；测试替身、fixture、mock adapter 或 local-only adapter 只能用于声明允许的范围。
+- `consistency_requirements`: 事务、锁、幂等键、唯一约束、审计保留、缓存失效、离线同步或 `not_applicable`。
+
+## 4. Async And Worker Boundary
+
+- `async_required`: `yes` / `no`
+- `scheduling_model`: `DB polling` / `MQ consumer` / `cron` / `event bus` / `browser event` / `manual command` / `none`
+- `concurrency_control`: `DB row lock` / `optimistic CAS` / `distributed lock` / `single process` / `browser single-thread` / `none`
+- `time_source`: `database time` / `server time` / `event time` / `browser time` / `not_applicable`
+
+## 4.1 Backend Layering And Error Boundary
+
+如果项目包含后端服务、BFF、worker API 或命令式写路径，至少补齐：
+
+- `controller_policy`: Controller / Handler 只负责请求解析、权限入口、调用 service、响应映射；不堆业务规则。
+- `service_policy`: Service 负责业务逻辑、事务编排、幂等和副作用协调；不得直接依赖 `req/res/ctx/request/response`。
+- `repository_policy_detail`: Repository / DAO 负责数据库访问、查询组合和持久化边界；不返回页面展示字段。
+- `dto_policy`: DTO / Request / Response / Entity 的边界和禁止混用规则。
+- `error_handling_policy`: 全局异常处理、错误码模型、用户可见错误、日志保留策略。
+- `transaction_boundary`: 哪些写路径必须事务化，哪些步骤不得跨外部调用长持锁。
+- `idempotency_policy`: 哪些入口必须幂等，幂等键放在哪里，重复请求返回什么。
+
+## 5. Test Double Policy
+
+- `test_double_allowed_scope`: `unit_tests_only` / `contract_tests` / `local_demo` / `domain_prototype` / `not_allowed` / `project_defined:<rule>`
+- `mock_as_acceptance_evidence`: `no` by default；如果允许，必须写明原因、适用依赖、过期条件和替代真实验证计划。
+- `minimum_integration_evidence`: 列出当前项目最低真实验证组合，例如 UI + API、API + DB、CLI + filesystem、package API + consumer test、worker + queue，或 `not_applicable`。
+
+## 6. Forbidden Implementations
+
+按项目填充，不要只写抽象原则。示例只作为选项，不代表所有项目都适用：
+
+- 不允许只实现领域 service 而没有任务声明的公开入口。
+- 不允许公开契约有 operation 但代码没有对应实现或验证。
+- 不允许用测试替身、mock、fixture、local-only adapter 冒充声明交付路径。
+- 不允许把 `domain_prototype` 标记为可交付功能完成。
+- 不允许只运行 `git diff --check` 就声明 `feature_impl` 完成。
+
+## 7. Architecture Fitness Checks
+
+每个项目至少定义一个可运行或可审查的架构适配检查，并把命令或检查项同步到 `task.json` 的 `test_command`。
+
+```powershell
+<replace-with-project-fitness-check>
+```
+
+若暂时没有脚本，必须在 `docs/testing/verify-matrix.md` 写明等价检查项。可选检查包括：
+
+- 声明的生产入口存在，且能被启动、导入、访问或执行。
+- 公开接口与实现、测试和证据路径可追踪。
+- 声明交付路径未引用禁止的测试替身。
+- 需要持久化、worker、浏览器、文件或第三方服务时，存在对应的真实验证证据。
+- 不适用的边界已明确标记为 `not_applicable`，而不是留空。
+
+## 8. Definition Of Done
+
+- `architecture_constraints` 已从本文件或等价 truth source 复制到每个相关 `feature_impl` 任务。
+- 多服务、多仓库或契约任务已把服务矩阵、受影响服务和 change gates 复制到相关 `feature_impl` 的 `context_files`、`architecture_constraints`、`qa_contract` 和 `test_command`。
+- `forbidden_implementations` 已覆盖当前项目最容易跑偏的替代实现。
+- `test_command` 包含项目适配检查、affected tests、必要契约/集成/端到端验证和 `git diff --check`。
+- Stage 1 Review 对声明的架构形态给出 PASS。
+- 完成声明能说明声明交付路径、测试替身和不适用边界。

package/package-source/docs/codex-harness-engineering/templates/docs/code-semantics-and-navigation.md

@@ -0,0 +1,54 @@
+# 代码语义与导航层
+
+本文定义项目里的导航顺序，帮助 agent 先找到入口，再进入具体实现。
+
+## 默认顺序
+
+1. `docs/ai/repo-map.md`
+2. `docs/ai/architecture-brief.md`
+3. `docs/ai/CURRENT_TASK.md`
+4. 代码语义工具或全文搜索
+5. `docs/knowledge/*`
+
+## 职责边界
+
+- `docs/ai/*`: 文档导航层
+- 代码语义工具: 定义、引用、调用链、影响面
+- `docs/knowledge/*`: 历史经验和长期可复用知识
+
+## `docs/ai/*` 最低字段
+
+- `repo-map.md`
+  - 关键目录
+  - 阅读顺序
+  - 代码入口
+  - 调用链提示
+  - 测试入口
+  - 配置入口
+  - 禁改区
+- `CURRENT_TASK.md`
+  - 任务目标
+  - 验收标准
+  - owned paths
+  - 模块归属
+  - 类似实现
+  - 影响调用方
+  - 验证命令
+  - no-touch 区域
+- `API_MAP.md`
+  - 路由、命令、脚本或接口入口
+  - 配置接口
+  - 错误/认证入口
+- `DB_SCHEMA.md`
+  - 数据入口
+  - 关键实体
+  - 约束或持久化边界
+
+## 影响面分析最少回答
+
+- 入口在哪里
+- 上游是谁
+- 下游是谁
+- 受影响文件有哪些
+- 受影响测试和验证命令有哪些
+- 路由、权限、中间件、环境变量、build/deploy 是否会受影响