From 715182e34c8f5985ea2dccf0a423ce5d06e0f88f Mon Sep 17 00:00:00 2001 From: Linghong Date: Wed, 23 Sep 2026 06:22:58 +0000 Subject: [PATCH] =?UTF-8?q?=E8=AF=B4=E6=98=8E=E7=AD=96=E5=88=92=20Agent=20?= =?UTF-8?q?=E6=8F=90=E7=A4=BA=E8=AF=8D=E8=B7=AF=E5=BE=84=E5=A5=91=E7=BA=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 补充策划工作区和固定资源包相对路径的使用方式。 在共享踩坑记录中说明这些路径不属于误暴露的宿主实现。 --- docs/project-memory/shared-memory/pitfalls.md | 4 ++++ ...【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md | 7 +++++++ 2 files changed, 11 insertions(+) diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md index d269c8c32..54c8f7deb 100644 --- a/docs/project-memory/shared-memory/pitfalls.md +++ b/docs/project-memory/shared-memory/pitfalls.md @@ -1,5 +1,9 @@ # 踩坑与排障记录 +## 策划 Agent 提示词中的相对路径不要当作内部实现删去 + +`project/...` 是 Agent 读写策划工作区的目标路径，`resources/...` 是查找内置分册、模板和例子的资源定位；即使阶段上下文也注入了同一产物路径，提示词里的路径仍是 Agent 需要的契约。清理宿主实现细节时不要误删这些相对路径，具体用法见[策划 Agent 路径说明](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md#6-阶段与提示词注入)。 + ## AGC 素材直传的 OSS 权限必须同步到 Native shell 契约检查 - **现象**：Native shell CI 在 `check:native-shells:contract` 的 HTTP scope 检查失败，尚未准备 Rust 缓存；后续导出步骤正常退出但实际跳过，导致 master 缓存产物缺组、自动镜像刷新等待。 diff --git a/docs/technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md b/docs/technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md index 5aae2efe7..ecbb3008a 100644 --- a/docs/technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md +++ b/docs/technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md @@ -276,6 +276,13 @@ concept → top_design → architecture → systems → tdd → consultant `systems: []` 是已确定的行为，不是迁移时需要补齐的缺口。`project/analysis.md`、`project/决策台账.md`、`project/dialog.md` 保持原型中的共享过程文件口径，不升级为新的审批必需项。速览卡保留原型结构提示，但 Runtime 与 UI 不解析其章节或内容字段。 +提示词中的路径是策划 Agent 使用的相对路径约定： + +- `project/...` 以策划工作区为根，Agent 将其传给 `read_file`、`write_file`、`patch_file` 等文件工具来读取和维护正式产物及过程文件。宿主将它映射到项目的 `design_artifacts/project/...`；阶段审批按登记的相对路径检查必需产物。提示词写明 `project/速览卡.md`、`project/analysis.md` 等目标位置，是在告诉 Agent 文件应写在哪里，并非泄露宿主绝对路径。 +- `resources/skills/...`、`resources/templates/...`、`resources/exemplars/...` 和 `resources/modules/system-types/...` 指向随应用发布的固定策划资源包，用于定位分册、模板、例子及系统类型资料，不是策划工作区的写入目标。资源目录在 `resources/catalog.json` 中登记相对路径与资源 ID；Agent 可用 `list_resources` 查 ID，再用 `read_resource` 按 ID 读取。分册中省略 `resources/` 前缀的 `templates/...` 等写法仍指同一资源包内的位置。 + +这些路径直接服务于 Agent 的文件操作和资源查阅，属于提示词应保留的契约；即使阶段上下文也注入了某条产物路径，分册和模板中的路径仍提供目标文件与交叉引用的具体定位。去除客户端与宿主实现细节时，不应把这类相对路径当作意外暴露的内部实现；宿主安装目录、项目绝对路径及会话控制文件位置才不属于 Agent 的操作输入。 + 过程文档记录关键依据、决定和待办，不要求实时完整，也不应重复正式设计文档；阶段提交前补齐影响验收的关键记录。顶层设计的分册、模板和示例保留核心定位及按需说明的易混淆方向与排除理由，不强制使用固定的“不是 X，而是 Y”句式。 进入下一阶段必须由用户批准触发。Runtime 推进后向 Agent 追加明确的用户行为语义，例如“用户已批准上一阶段，现在进入顶层设计阶段”，避免 Agent 误认为 Runtime 自行推进。