frontend-project-context 1.7.0 → 1.9.1

package/docs/29-REAL-PROJECT-1.8.0-INITIALIZATION-OBSERVATIONS.md

@@ -0,0 +1,228 @@
+# 1.8.0 真实项目初始化与上下文观察记录
+
+> 状态：`observation-only / discussion-only / draft`
+>
+> 日期：`2026-09-16`
+>
+> 目标项目：`/Users/fushan/开发/tmc/dtg-tmc-pc`
+>
+> 目标分支：`dev_agent20160904`
+>
+> 安装版本：`frontend-project-context@1.8.0`
+
+## 1. 记录目的与边界
+
+本文只归档 `frontend-project-context@1.8.0` 在真实项目中的正式初始化过程、任务 Context 实测和新 Host 审查结果，供后续集中整理问题时使用。
+
+本文不是产品设计、路线图、缺陷裁定、Project Contract、实现授权、发布授权或真实项目业务代码修改授权。文中“已确认”“观察风险”“待真实任务验证”必须保持区分；不得因为单次真实项目现象直接扩大 discovery、修改内核或形成新版本实现。
+
+本轮观察者不替代真实 Host 执行初始化，不修改目标项目业务代码，不提交或推送任何仓库。
+
+## 2. 正式初始化结果
+
+真实 Host 严格使用目标项目本地安装的 `frontend-project-context@1.8.0` 和包内唯一指令 `ai-project-initialization@1` 执行初始化。
+
+初始化指令摘要：
+
+```text
+sha256:8ec3bbf0202c3893514325db3f48d23adbcf18d7668b9731ac4f10e2a3be4d9e
+```
+
+人工集中审查绑定：
+
+- 12 个来源；
+- 16 个 Contract item；
+- proposal 摘要 `sha256:5fa3c7a974adae911fe448505a765fce4d64e80f6908c34eaccc104908466e36`；
+- `AGENTS.md` 人工区域不修改；
+- 只追加 renderer 4 受管 AI Entry；
+- reviewer 为 `fushan`。
+
+机械应用和 Phase E 完成后的结果：
+
+- `health=clean`；
+- `contractReadiness=contract-ready`；
+- `check` 无 findings；
+- AI Entry renderer 4，状态 `current`；
+- 12 个 active source；
+- 16 个 approved item；
+- Contract 摘要 `sha256:144eb00d0a5ef1c6f6c531ca3147d179d500b6ecedd6008adf4e62ba1dc96fd1`；
+- `setup.proposal.json` 与 `initialization.proposal.json` 已删除；
+- 无本轮 Action Plan、Review Bundle、receipt、日志或初始化缓存残留；
+- 未修改业务代码。
+
+代表性 Context 验证覆盖 project、`src` path-prefix、router/http/store/build file scope，文件级 sibling isolation 成立。
+
+## 3. 生成文件的实际职责
+
+| 文件 | 本轮确认的职责 |
+| --- | --- |
+| `.project-context/contract.json` | 保存人工批准的长期事实、规则、引用和验证描述，是 Context Bundle 的语义来源 |
+| `.project-context/sources.lock.json` | 锁定来源摘要，用于发现来源漂移 |
+| `.project-context/projections.lock.json` | 记录 `AGENTS.md` 受管区域所有权和 renderer 状态 |
+| `AGENTS.md` 受管区域 | 让新 Host 先检查 Project Context 状态并按目标路径编译任务 Context |
+
+三份 store 和 AI Entry 共同建立治理、来源、作用域、所有权和漂移检查闭环；它们不自动形成组件调用图、接口字段语义或业务任务实现知识。
+
+## 4. 普通 Vue 任务 Context 实测
+
+本轮对以下两个不同目标和任务执行了实际 Context 编译：
+
+1. `src/views/flight/list/index.vue`：修改航班列表页面的行李信息展示；
+2. `src/components/flight/non-whitelist-confirm.vue`：调整非白名单航班确认弹窗的行李信息展示。
+
+两份 Bundle 除任务文字和目标路径外，命中内容基本相同：
+
+- 项目技术栈；
+- 可用 scripts；
+- 授权边界；
+- 格式化与提交钩子；
+- 工作流选择；
+- 用户工作区保护；
+- `src` 级国际化规则；
+- `src` 级源码复用原则；
+- 项目入口与 OpenSpec 引用；
+- 风险验证描述。
+
+两份 Bundle 均未直接提供：
+
+- Vue 组件 props、events 和实际数据结构；
+- 调用方与被调用方；
+- 对应接口、字段映射和请求链路；
+- 行李展示的稳定业务规则；
+- 往返、多程、国内、国际等业务差异；
+- 可直接复用的相邻实现；
+- 本次任务的精确验证路径。
+
+因此，当前 Contract 对普通 Vue 文件的新增价值主要是项目治理、安全边界、通用开发规则和来源可追溯性；具体功能实现仍需要 Host 动态调查目标文件、调用方、接口和相邻实现。
+
+## 5. 已确认问题
+
+### O-01 普通业务文件的 Context 区分度不足
+
+两个不同机票 Vue 目标实际获得了近似相同的通用 Bundle。当前 scope compiler 工作正常，但 Contract 没有提供机票域或组件级稳定语义，因此不能仅凭 Bundle 明显提高具体业务修改的准确度。
+
+这不等于应该把所有业务源码注册为长期真源。后续需要通过真实任务判断哪些稳定业务边界值得进入 Contract，哪些应继续由 Host 动态调查。
+
+### O-02 未知目标路径时存在启动歧义
+
+AI Entry 要求根据真实任务确定路径后编译 Context；仓库人工规则又要求先全仓定位。对于只有现象、尚不知道文件位置的任务，Host 可能在“先定位源码”和“先编译精确 Context”之间发生循环。
+
+候选收口方向是粗粒度定位 Context 与精确多路径 Context 两阶段，但本文不冻结具体协议。
+
+### O-03 单路径示例不足以表达多文件任务
+
+CLI 可以表达多个目标路径，但 AI Entry 示例只展示一个 `<RELATIVE_PATH>`。真实任务同时涉及页面、组件、API、store、router 或构建文件时，只传主文件会遗漏其他文件的精确 scope policy。
+
+### O-04 `read targets` 要求缺少结构化输出支持
+
+AI Entry 要求 Host 报告必要 read targets；实际 `context --json` 只返回一个 Markdown `content` 字段，Bundle 中只有 Source index，没有结构化区分：
+
+- required read targets；
+- conditional read targets；
+- provenance-only sources；
+- 已被 Contract statement 充分替代的来源。
+
+Source index 不能直接等同于全部必读文件，否则普通 Vue 任务会重新读取 `vue.config.js`、`.husky/pre-commit`、`openspec/config.yaml` 等不一定相关的来源。
+
+### O-05 `AGENTS.md` 与 Contract 重复较多
+
+当前人工 `AGENTS.md` 已包含技术栈、目录、命令、格式、路由、HTTP、Vuex、国际化、构建和授权规则；Context Bundle 又重新输出其中一部分。
+
+实际链路可能变成：
+
+```text
+自动读取完整 AGENTS
+→ 编译 Context
+→ 再收到 AGENTS 规则摘要
+→ Source index 再次指向 AGENTS/docs
+```
+
+这降低了最小读取和按 scope 分发的增量价值。Contract 语义覆盖充分以前，不应直接删除 AGENTS 人工规则。
+
+### O-06 `source.entry` 将人工真源与受管投影绑定在同一摘要中
+
+多个 Contract item 使用整个 `AGENTS.md` 作为 `source.entry`，而该文件同时包含 Project Context 自己维护的 marker 区。未来 renderer 升级或 AI Entry 文案变化可能造成产品自身引起的 source drift，并牵连并未变化的人工事实。
+
+可能方向包括只摘要人工区域或把长期规则迁入独立人工真源；本文不选择实现方案。
+
+### O-07 关键域处置没有形成可供后续 Host 查询的持久 coverage 结论
+
+初始化集中审查曾逐项说明关键开发域已纳入、排除或动态调查；但后续 `coverage-audit` 仍显示 `registrationCoverage=not-declared`，具体排除和动态调查结论没有以清晰持久结构提供给新 Host。
+
+`contract-ready` 当前只能证明 Contract 结构、来源、审批和作用域编译有效，不能被解释为所有业务语义覆盖完整。
+
+### O-08 产品能力边界与 Host 开发权限的交接不够明确
+
+`status` 中的 `businessCodeWrites=false` 和 `taskExecution=false` 表示 Project Context 产品自身不执行开发任务；新 Host 可能误解为当前开发请求也禁止修改代码。AI Entry 尚未明确说明 Context 编译完成后如何回到人工规则和当前用户请求判断 Host 的任务权限。
+
+## 6. 观察风险，尚未裁定为产品缺陷
+
+### R-01 `attention` 可能抢占无关真实任务
+
+AI Entry 要求在 `attention` 时执行 `sync` 返回的维护工作单元，但没有在入口中明确区分与当前目标相关和无关的漂移。需要真实分支和日常开发观察后再判断是否会阻断无关任务。
+
+### R-02 宿主的外部 memory 仍可能进入推理链
+
+新的审查 Host 在读取当前项目前访问了 `/Users/fushan/.codex/memories/MEMORY.md`。因此该窗口不能作为仅凭初始化后目标项目完成接管的无历史证明。
+
+这首先属于 Host/平台偏离和外部条件：Project Context 可以声明外部记忆不是项目真源，但未必能阻止更高优先级的平台机制读取它。后续验收必须显式区分“读取过外部 memory”和“是否把外部 memory 当成项目事实”。
+
+### R-03 新 Host 最终报告存在 item 数量误差
+
+新 Host 报告当前 Contract 有 14 个 approved item；实际为 16 个。可能遗漏了两个 reference item：
+
+- `reference.openspec-workflow`；
+- `reference.project-guidance`。
+
+该问题属于 Host 报告质量，不直接证明 Contract 错误。
+
+## 7. 当前合理且应保留的能力
+
+- 项目本地精确版本和 `npm exec --offline` 阻止隐式版本漂移；
+- 人工 Project Contract、稳定 ID、来源和显式审批成立；
+- AI Entry 只拥有 marker 区，人工区域所有权清晰；
+- `status`、`sync` 和 `context` 默认只读；
+- Contract、source lock、projection lock 当前一致；
+- 文件级 scope 与 sibling isolation 实际生效；
+- router、HTTP、store、build policy 不会污染普通业务页；
+- Contract 不自动扩张业务代码、提交、推送、发布或外部副作用权限；
+- 模板 README、生成物、历史任务实例和虚构测试能力没有被提升为长期真相。
+
+## 8. 尚不能得出的结论
+
+本轮不能证明：
+
+- 当前 Contract 已包含所有业务语义；
+- 普通 Vue 任务仅靠 Context Bundle 就能完成正确修改；
+- 每个 Source index 都应由 Host 读取；
+- 外部 memory 已被 Project Context 隔离；
+- `attention` 一定会阻断无关开发；
+- 任一观察项已经获得产品修复、设计或下一版本授权。
+
+## 9. 后续真实开发的观察清单
+
+下一次在同一分支使用无历史 Host 执行真实业务需求时，重点记录：
+
+1. Host 是否只从目标项目入口发现并消费 Project Context；
+2. 目标路径未知时如何完成首次定位；
+3. 是否在识别多个受影响文件后重新编译多路径 Context；
+4. 实际报告的 item IDs、scope 和 read targets 是否准确；
+5. Source index 是否引发不必要的重复读取；
+6. 通用 Contract 是否减少错误命令、越权、全仓格式化或危险构建；
+7. 缺少业务域语义是否导致漏读调用方、接口或相邻实现；
+8. Context 不足时 Host 是否明确报告 gap，而不是猜测；
+9. 真实修改完成后 Project Context 是否仍为 `clean`；
+10. 哪些缺口属于产品协议、目标项目 Contract 数据、Host 偏离或外部平台条件。
+
+## 10. 后续整合原则
+
+在真实开发链路完成前，保持目标项目安装的 `1.8.0` 不变，不边走边修改产品或目标项目内部 store。观察项应先按以下类型归类：
+
+- 产品协议缺口；
+- 目标项目 Contract 数据缺口；
+- AI Entry/消费者适配问题；
+- Host 行为偏离；
+- 外部平台条件；
+- 尚未证实的风险。
+
+完成至少一个真实业务任务后，再基于本记录和新证据集中决定哪些问题需要进入设计。任何设计、Contract 修订、产品实现、Git 操作和发布仍需单独授权。