Skip to content

Commit 7442a59

Browse files
sincerely90sincerely90
committed
docs(plan): 规划移除 bridge JSON 与 context pack 产品面
新增 follow-up 计划，明确删除 implementation-bridge 默认 JSON 输出， 并将 context pack 从公开产品面移除，正常 happy path 直接进入 ce-work。
1 parent 02716f2 commit 7442a59

1 file changed

Lines changed: 187 additions & 0 deletions

File tree

‎docs/plans/2026-06-14-001-refactor-remove-bridge-json-and-context-pack-surface-plan.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
---
2+
title: "refactor: Remove bridge JSON and public context pack surface"
3+
type: refactor
4+
date: 2026-06-14
5+
---
6+
7+
# refactor: Remove bridge JSON and public context pack surface
8+
9+
## Summary
10+
11+
删除 `aisee:implementation-bridge` 的默认 JSON 产品输出，并把 `context pack` 从公开产品面移除。正常情况下，`implementation-bridge` 直接进入 `ce-work`；异常情况下只输出简短阻塞说明。项目记忆与团队知识注入改为通过更直接的 memory / knowledge 入口完成，不再保留 `context pack` 这层公开产品能力。
12+
13+
---
14+
15+
## Problem Frame
16+
17+
上一轮收缩已经把 `context pack` 收薄，把 `implementation-bridge` 改成“读取策略 + `tasks.md` / apply tracks / evidence 回写提醒”。但当前仍有两层无效复杂度：
18+
19+
1. 当 change 已经 `ready` 时，bridge 还会把结构化 JSON 暴露给用户。
20+
2. `context pack` 作为公开命令仍然存在，即使它已经不再承担 execution / verify / review 投影职责。
21+
22+
这会带来几个明确问题：
23+
24+
- 用户被迫理解不该由自己处理的中间产物。
25+
- `ce-work` 如果不显式消费 bridge JSON，这段 JSON 就不是实际 handoff 协议。
26+
- `context pack` 如果除了 memory / knowledge 注入以外不再有独立价值，就不应该继续作为公开产品能力保留。
27+
- 产品看起来还存在一层 machine contract 和一层 context bus，但默认 happy path 没有真实消费者，复杂度大于价值。
28+
29+
因此，本轮不再停留在“继续弱化”的中间态，而是直接删除：
30+
31+
- `implementation-bridge` 的默认 JSON 产品面；
32+
- `context pack` 的公开产品面。
33+
34+
---
35+
36+
## Requirements
37+
38+
- R1. 当当前 change 满足进入实现的最低条件时，`aisee:implementation-bridge` 默认不再展示完整 JSON，而是直接进入或明确交给 `ce-work`。
39+
- R2. `aisee:implementation-bridge` 必须继续保留完成提醒：`ce-work` 完成当前批次前，必须回写 `tasks.md` 或当前 schema 的 apply tracks，并补验证证据入口。
40+
- R3. 当当前 change 存在 blocker、关键缺口或读取入口失效时，`aisee:implementation-bridge` 应输出简短、面向人的阻塞结果，而不是默认大段 JSON。
41+
- R4. `context pack` 从公开产品面删除；默认工作流、README、workflow、best-practices 和 CLI 参考中不再出现它。
42+
- R5. 项目记忆与团队知识的 change-scoped 注入改为通过更直接的 memory / knowledge 查询入口完成，不再依赖 `context pack` 这层公开命令。
43+
- R6. README、workflow、best-practices、skill eval 和 bridge references 必须同步更新，不再宣称默认输出是 JSON 判定结果，也不再把 `context pack` 当成主流程能力。
44+
- R7. 本轮不要求 `ce-work` 新增对 bridge JSON 的显式消费；这正是本轮要避免的方向。
45+
46+
---
47+
48+
## Key Technical Decisions
49+
50+
- KTD1. **Happy path 直接路由。** `implementation-bridge` 在 `status=ready` 时默认直接进入 `ce-work`，而不是向用户展示 bridge JSON。
51+
- KTD2. **异常时给短结果，不给大 JSON。** 只有 `blocked`、`needs_attention` 或关键 artifact / schema 读取失败时，才输出简短结构化说明。
52+
- KTD3. **桥接 JSON 直接退出产品面。** 不再为默认交互保留公开 bridge JSON；本轮也不新增 `ce-work` 对其的消费逻辑。
53+
- KTD4. **完成提醒保留。** 即使去掉默认 JSON，bridge 仍然必须向 `ce-work` 强调 apply tracks / evidence 写回规则。
54+
- KTD5. **`context pack` 退出公开命令面。** 既然它只剩 memory / knowledge 注入价值，就不再以独立公开产品能力存在；相关注入改由 memory / knowledge 能力直接承担。
55+
- KTD6. **不把新目标误做成“教 ce-work 消费 JSON”。** 本轮目标是删掉无默认消费者的产品输出和无独立价值的公开命令，不是把它们升级成正式 machine handoff 协议。
56+
57+
---
58+
59+
## High-Level Technical Design
60+
61+
```mermaid
62+
flowchart TB
63+
A["implementation-bridge"] --> B{"current change ready?"}
64+
B -->|yes| C["directly hand off to ce-work"]
65+
B -->|no| D["show concise blocker / needs-attention result"]
66+
C --> E["ce-work reads current change artifacts"]
67+
E --> F["write back tasks.md / apply tracks / evidence"]
68+
D --> G["user decides whether to repair artifacts first"]
69+
```
70+
71+
```mermaid
72+
flowchart LR
73+
A["public context pack command"] --> X["removed"]
74+
B["aisee memory / aisee knowledge"] --> C["direct injection entry"]
75+
C --> D["implementation / verify guidance"]
76+
```
77+
78+
---
79+
80+
## Scope Boundaries
81+
82+
In scope:
83+
84+
- 收掉 `implementation-bridge` 默认 JSON 产品输出。
85+
- 删除 `context pack` 的公开产品面。
86+
- 保留并强化默认进入 `ce-work` 的 happy path。
87+
- 保留 `tasks.md` / apply tracks / evidence 完成提醒。
88+
- 同步更新 skill、eval、README、workflow、best-practices、CLI 参考和 bridge references。
89+
90+
Out of scope:
91+
92+
- 让 `ce-work` 新增 bridge JSON 消费逻辑。
93+
- 重写 verify/archive-guard 主流程。
94+
- 新建跨 skill 的 machine handoff 协议。
95+
96+
### Deferred to Follow-Up Work
97+
98+
- 如果未来明确需要 machine handoff 协议，再单独设计 debug / machine mode 的 JSON 合同，而不是复用默认产品输出。
99+
- 如果 memory / knowledge 需要新的 change-scoped 便捷入口，再单独规划更直接的 query 命令或 skill 路由。
100+
101+
---
102+
103+
## Risks & Dependencies
104+
105+
- 风险 1：仓库文案已经改了，但实际宿主运行时仍可能因为缓存而展示旧 JSON。
106+
- 缓解：在计划中明确区分 repo 合同与宿主缓存问题；本轮只修 repo 默认行为。
107+
- 风险 2：如果默认直接进入 `ce-work`，但桥接阶段没有保留 `tasks.md` / apply tracks 回写提醒，执行收口会退化。
108+
- 缓解：把完成提醒视为不可删除的 happy-path guardrail。
109+
- 风险 3：README / skill eval 若继续写“默认输出 JSON 判定结果”或仍把 `context pack` 当公开能力，会让产品心智反复回流。
110+
- 缓解：所有默认输出和 `context pack` 公开面相关文案一次性收口。
111+
112+
---
113+
114+
## Sources & Research
115+
116+
- `docs/plans/2026-06-13-001-refactor-context-pack-memory-companion-plan.md`
117+
- `plugins/aisee-plugin/skills/aisee-implementation-bridge/SKILL.md`
118+
- `plugins/aisee-plugin/references/compound-bridge.md`
119+
- `docs/workflow.md`
120+
- `docs/best-practices.md`
121+
- `/Users/fengliang/.codex/plugins/cache/compound-engineering-plugin/compound-engineering/3.12.0/skills/ce-work/SKILL.md`
122+
123+
外部研究未运行。本轮问题是当前 repo 内的交互职责与公开产品面收口，不依赖外部资料。
124+
125+
---
126+
127+
## Implementation Units
128+
129+
### U1. Remove default JSON from implementation-bridge happy path
130+
131+
- **Goal:** 让 `implementation-bridge` 在 `ready` 时默认不展示大段 JSON，而是直接交给 `ce-work`。
132+
- **Requirements:** R1, R3, R7
133+
- **Dependencies:** none
134+
- **Files:**
135+
- `plugins/aisee-plugin/skills/aisee-implementation-bridge/SKILL.md`
136+
- `plugins/aisee-plugin/skills/aisee-implementation-bridge/evals/evals.json`
137+
- `plugins/aisee-plugin/skills/aisee-implementation-bridge/agents/openai.yaml`
138+
- `tests/test_skill_cli_preflight.py`
139+
- **Approach:** 把 skill 合同从“默认输出 JSON 判定结果”改成“ready 时直接进入 `ce-work`；只有异常时输出简短阻塞说明”。同步收口 eval 与 agent prompt，避免默认输出行为和文案脱节。
140+
- **Patterns to follow:** 沿用当前 bridge 已经收好的“当前 change facts 优先”与“不替代 `ce-work`”边界。
141+
- **Test scenarios:**
142+
- happy path 文案不再要求默认输出 JSON。
143+
- eval 不再把任何 JSON 字段当默认输出要求。
144+
- skill preflight 仍保留 apply tracks 回写提醒。
145+
- **Verification:** skill 合同测试通过，默认 happy path 语义明确指向 `ce-work`。
146+
147+
### U2. Remove context pack from the public product surface
148+
149+
- **Goal:** 让 `context pack` 从公开产品面退出，不再作为 README、workflow、CLI 参考或默认流程的一部分。
150+
- **Requirements:** R4, R5, R6
151+
- **Dependencies:** U1
152+
- **Files:**
153+
- `src/aisee_cli/__main__.py`
154+
- `README.md`
155+
- `README.en.md`
156+
- `docs/workflow.md`
157+
- `docs/workflow.en.md`
158+
- `docs/best-practices.md`
159+
- `docs/best-practices.en.md`
160+
- `docs/compatibility-policy.md`
161+
- `docs/compatibility-policy.en.md`
162+
- **Approach:** 从公开 CLI 参考与默认流程中移除 `context pack`。项目记忆与团队知识注入改为通过更直接的 memory / knowledge 能力完成；bridge / verify / archive 文案不再把 `context pack` 视为主路径。
163+
- **Patterns to follow:** 复用上一轮已经建立的 “OpenSpec facts 直接读取 + 可选 guidance” 边界。
164+
- **Test scenarios:**
165+
- README / workflow / best-practices 中不再把 `context pack` 当默认产品能力。
166+
- CLI 参考不再列出 `context pack` 作为主流程命令。
167+
- compatibility 文档说明其退出公开产品面。
168+
- **Verification:** 文档全文搜索不再把 `context pack` 作为主流程默认入口。
169+
170+
### U3. Preserve concise blocker mode and completion reminders
171+
172+
- **Goal:** 去掉默认 JSON 与 `context pack` 后，保留 bridge 在异常路径下的最小可用提示，以及 `tasks.md` / apply tracks / evidence 完成提醒。
173+
- **Requirements:** R2, R3
174+
- **Dependencies:** U1, U2
175+
- **Files:**
176+
- `plugins/aisee-plugin/skills/aisee-implementation-bridge/SKILL.md`
177+
- `plugins/aisee-plugin/skills/aisee-implementation-bridge/references/brief-template.md`
178+
- `plugins/aisee-plugin/skills/aisee-implementation-bridge/references/brief-index-template.md`
179+
- `plugins/aisee-plugin/references/compound-bridge.md`
180+
- **Approach:** 将异常路径收口成简短的人类可读结果：缺什么、为什么不能继续、要先修哪里。保留当前 bridge 对 `tasks.md` / apply tracks / evidence 的强提醒，但不要求这些提醒必须通过公开 JSON 或 `context pack` 传达。
181+
- **Patterns to follow:** 继续沿用现有 “完成前必须先回写 apply tracks” 的严格规则。
182+
- **Test scenarios:**
183+
- blocker 路径仍能明确指出读取入口失效或关键 artifact 缺失。
184+
- brief 模板仍强调 apply tracks 与 evidence 回写。
185+
- compound bridge 引用不再把 JSON 或 `context pack` 当主 handoff 形态。
186+
- **Verification:** bridge 文案在 happy path 与异常路径下都清晰，不再混杂默认 JSON 心智。
187+

0 commit comments

Comments
 (0)