Back to blog shelf

Notes · 2026/09/13

Context Guard文件设计

底层的文件系统如何设计非常重要，也非常复杂。
目前MVP状态的context guard对文件系统做了如下的设计
整体采用多层index设计，让agent只读到他需要读的内容

project/
├── root_index.md            # 顶层：全局模块与节点索引
├── 前端设计-module/
│   ├── index.md             # Module_index：模块描述、Related/Sub、Bug/Todo/Idea
│   ├── bugs/
│   │   ├── B001.md
│   │   └── B002.md          # bug.md：现象、纠正事件、复现、归因、测试、Trace
│   ├── todos/
│   │   └── T001.md
│   ├── ideas/
│   │   └── I001.md
│   └── Bug按钮-node/
│       └── index.md         # Node_index：节点级索引
└── 权限管理-module/
    └── index.md

Module_index.md

前端设计

定义界面结构与交互。

关联模块与节点

Sub

Bug

Todo

Idea

Node_index.md

Bug按钮

提交当前节点的缺陷反馈。

关联模块与节点

Sub

NULL

Bug

B002 一次反馈操作产生多条相同记录

点击 Bug 按钮提交反馈后，列表里出现两条一样的内容。不确定是不是点了两次。
Status: Resolved

Todo

Idea

I002 反馈时附带当前节点信息

减少用户手工描述问题位置。
Status: Proposed

节点状态：

Bug	`Open` 待处理、`InProgress` 处理中、`Pending` 待验收、`Resolved` 已验证解决
Todo	`Open` 待处理、`InProgress` 进行中、`Done` 已完成、`Cancelled` 已取消
Idea	`Proposed` 待讨论、`Accepted` 已采纳、`Rejected` 不采纳

bug.md格式

B002 标题

Reporter: Human
Status: Resolved
CurrentAttempt: A2

1. 现象

原始描述。

2. 后续纠正事件

A1 / Refuted：纠正说明。
A2 / Confirmed：修复结论。

3. 复现

A1

复现方法。

A2

复现方法。

4. 原因与代码改动

当前有效结论

简要结论。

A1

Status: Refuted
RefutedBy: A2
Refutation: 推翻依据。

原因：保留当时的归因。

code index

文件
改动简述。

A2

Status: Confirmed

原因：本轮归因。

code index

文件
改动简述。

5. 测试

A1：结果简述。
A2：结果简述。

6. 修复 Session 索引

bug.md示例

B002 一次反馈操作产生多条相同记录

Reporter: Human
Status: Resolved
CurrentAttempt: A4

拟真示例，非真实项目记录；以下测试与验收均为虚构，测试与 Trace 链接指向临时占位文件。
代码文件路径为虚构的仓库相对路径，因此不设置无效跳转；正式记录应使用对应真实代码版本的文件链接。

1. 现象

点击 Bug 按钮提交反馈后，列表里出现两条一样的内容。不确定是不是点了两次。

2. 后续纠正事件

A1 / Refuted：人类验收不通过；A2 复查只有一个事件处理器，“重复绑定”的归因被推翻。
A2 / Confirmed：同步锁解决单窗口重入；人类验收发现超时重试仍重复，不否定该原因。
A3 / Refuted：当轮人类验收通过；A4 发现并发重复，推翻“先查询再插入即可防重”的结论。
A4 / Confirmed：增加原子唯一约束，并发与重试测试通过，人类验收通过。

3. 复现

A1

填写反馈，连续点击提交两次，偶尔创建两条记录。

A2

在按钮禁用状态生效前连续触发提交，两次调用均发出请求。

A3

服务端创建成功后丢弃响应，客户端超时后重试，创建第二条记录。

A4

两个窗口使用同一请求键；让两个请求均完成查重后再插入，创建两条记录。

4. 原因与代码改动

当前有效结论

单窗口使用同步锁阻止重入；重试复用请求键，服务端用原子唯一约束防止重复创建。仅禁用按钮或先查后写都不充分。

A1

Status: Refuted
RefutedBy: A2
Refutation: 仅存在一个事件处理器，重复请求来自禁用状态生效前的重入。

原因：怀疑提交事件重复绑定，导致一次反馈触发两次请求。

code index

src/ui/FeedbackForm.tsx
提交后禁用按钮，防止重复点击。

A2

Status: Confirmed

原因：界面状态更新前存在重入窗口。

code index

src/ui/submitFeedback.ts
提交入口同步加锁，结束时释放，阻止单窗口重入。

A3

Status: Refuted
RefutedBy: A4
Refutation: 同键并发请求均可通过查询并各自插入，推翻“先查后写即可防重”的结论。

原因：超时重试未识别已创建的反馈，导致再次创建；复用请求键并在创建前查重即可防止重复。

code index

src/ui/submitFeedback.ts
同一次反馈重试复用请求键。
src/server/createFeedback.ts
创建前查询请求键，存在则返回旧记录。

A4

Status: Confirmed

原因：查重与插入不原子，并发请求可同时通过检查。

code index

src/storage/migrations/004_feedback_unique_key.sql
对用户与请求键建立组合唯一约束。
src/server/createFeedback.ts
原子创建，唯一键冲突时返回已有记录；同键不同内容则报冲突。

5. 测试

A1：按钮禁用后再次点击，未发出新请求，测试通过。
A2：同步重入只发一个请求，测试通过。
A3：响应丢失后顺序重试返回同一记录，测试通过。
A4：同键并发、超时重试均只创建一条；不同键允许独立创建；同键不同内容报冲突；前轮回归通过。

6. 修复 Session 索引

bug.md format

B002 Title

Reporter: Human
Status: Resolved
CurrentAttempt: A2

1. Symptoms

Original description.

2. Follow-up Corrections

A1 / Refuted: Correction description.
A2 / Confirmed: Repair conclusion.

3. Reproduction

A1

Reproduction method.

A2

Reproduction method.

4. Causes and Code Changes

Current Valid Conclusion

Brief conclusion.

A1

Status: Refuted
RefutedBy: A2
Refutation: Evidence disproving the cause.
Cause: Preserve the assessment made at the time.

code index

File
Brief change description.

A2

Status: Confirmed
Cause: This attempt's assessment.

code index

File
Brief change description.

5. Tests

A1: Brief result.
A2: Brief result.

6. Fix Session Index

bug.md example

B002 One Feedback Submission Creates Duplicate Records

Reporter: Human
Status: Resolved
CurrentAttempt: A4

Realistic fictional example, not a real project record; the tests and acceptance results below are fictional. Test and Trace links point to temporary placeholder files.
Code paths are fictional repository-relative paths, so no invalid navigation links are provided; actual records should use file links to the corresponding code revision.

1. Symptoms

After submitting feedback with the Bug button, two identical entries appear. I am not sure whether I clicked twice.

2. Follow-up Corrections

A1 / Refuted: Human acceptance failed. A2 found only one event handler, disproving duplicate event binding.
A2 / Confirmed: The synchronous lock prevents reentry in one window. Human acceptance found duplicates after timeout retries, which does not refute this cause.
A3 / Refuted: Human acceptance passed at the time. A4 found concurrent duplicates, disproving that checking before insertion is sufficient.
A4 / Confirmed: Added an atomic uniqueness constraint. Concurrency and retry tests passed; human acceptance passed.

3. Reproduction

A1

Fill in the feedback form and click Submit twice in succession. Two records are sometimes created.

A2

Trigger submission twice before the disabled button state takes effect. Both calls send a request.

A3

Drop the response after the server creates the record. Retry after the client times out. A second record is created.

A4

Use the same request key in two windows. Let both requests finish checking for an existing record before either inserts. Two records are created.

4. Causes and Code Changes

Current Valid Conclusion

Use a synchronous lock to prevent reentry in one window. Reuse the request key on retries and enforce atomic uniqueness on the server. Disabling the button or checking before insertion alone is insufficient.

A1

Status: Refuted
RefutedBy: A2
Refutation: Only one event handler exists. Duplicate requests come from reentry before the disabled state takes effect.
Cause: Suspected duplicate event binding causes one feedback submission to trigger two requests.

code index

src/ui/FeedbackForm.tsx
Disable the button after submission to prevent repeated clicks.

A2

Status: Confirmed
Cause: Reentry is possible before the UI state update takes effect.

code index

src/ui/submitFeedback.ts
Acquire a synchronous lock on entry and release it on completion to prevent reentry in one window.

A3

Status: Refuted
RefutedBy: A4
Refutation: Concurrent requests with the same key both pass the check and insert records, disproving that checking before insertion prevents duplicates.
Cause: Timeout retries do not recognize the feedback already created, causing another record to be created; reusing the request key and checking before creation will prevent duplicates.

code index

src/ui/submitFeedback.ts
Reuse the request key when retrying the same feedback operation.
src/server/createFeedback.ts
Check the request key before creation and return the existing record when found.

A4

Status: Confirmed
Cause: The check and insertion are not atomic, allowing concurrent requests to pass the check.

code index

src/storage/migrations/004_feedback_unique_key.sql
Add a composite uniqueness constraint on user and request key.
src/server/createFeedback.ts
Create atomically and return the existing record on a uniqueness conflict. Reject the same key with different content.

5. Tests

A1: Clicking again after the button is disabled sends no new request. Passed.
A2: Synchronous reentry sends only one request. Passed.
A3: A sequential retry after a lost response returns the same record. Passed.
A4: Same-key concurrency and timeout retries create one record. Different keys allow separate records. Same-key requests with different content are rejected. Earlier regression tests passed.

6. Fix Session Index

Bug Coordinater.md

Bug Coordinater

当任务为 Bug 模式时，负责编辑：

现象。
后续纠正事件中的人类反馈。

Bug Developer.md

Bug Developer

当任务为 Bug 模式时，负责编辑：

复现。
原因与代码改动、code index、当前有效结论。
后续纠正事件。
旧归因被推翻时，更新 Refuted、RefutedBy、Refutation，保留原始正文。

Bug Tester.md

Bug Tester

当任务为 Bug 模式时，负责编辑：

测试部分的场景与结果简述。

todo部分暂时沿用bug的格式

todo.md 示例

T002 补充反馈提交中的状态

Reporter: Human
Status: Done
CurrentAttempt: A4

四轮虚构示例；代码路径、测试与验收结果均为示例，测试和 Trace 链接为临时占位。

1. 需求

点击提交反馈后显示正在提交，避免用户不知道是否已经操作成功。

2. 后续调整事件

A1：完成按钮状态与成功、失败提示；人类补充超时场景，要求不能无限等待，交 A2。
A2：增加超时提示；测试发现旧请求晚到会覆盖重试状态，交 A3。
A3：隔离不同请求的状态；人类补充关闭再打开表单应保留未成功提交的草稿，交 A4。
A4：补充草稿保留，回归测试与人类验收通过。

3. 验收标准

A1

提交期间显示“提交中”，不能重复点击。
成功后显示成功反馈。
失败后显示失败反馈，按钮恢复可用，输入内容保留。

A2

超过 30 秒未收到响应，提示结果暂未确认，允许重试。
同一次操作的重试复用请求键，避免重复创建。
A1 标准继续适用。

A3

旧请求晚到不能覆盖新请求的状态。
A1、A2 标准继续适用。

A4

同一页面内关闭再打开表单，保留未成功提交的输入。
提交成功后清空草稿；刷新页面后的恢复不在本轮范围。
A1 至 A3 标准继续适用。

4. 方案与代码改动

当前有效方案

按请求标识更新状态，超时后允许复用请求键重试；草稿独立于表单保存，成功后清空。

A1

方案：由请求生命周期驱动按钮与结果提示，失败时保留输入。

code index

src/ui/FeedbackForm.tsx
按请求状态切换按钮文案和可用性。
src/ui/submitFeedback.ts
更新提交状态，区分成功与失败结果。

A2

方案：等待超过 30 秒转入超时提示，允许用户重试；沿用已有的服务端幂等接口。

code index

src/ui/submitFeedback.ts
增加超时计时，重试复用同一操作的请求键。
src/ui/FeedbackForm.tsx
增加超时文案与重试入口。

A3

方案：为每次请求分配标识，只允许当前请求更新状态。

code index

src/ui/submitFeedback.ts
回调更新状态前校验请求标识，忽略过期回调。

A4

方案：草稿存入页面级状态，表单关闭时不清空，提交成功后再清空。

code index

src/ui/feedbackDraft.ts
保存当前页面的未提交草稿。
src/ui/FeedbackForm.tsx
打开时恢复草稿，编辑时同步草稿。
src/ui/submitFeedback.ts
当前提交成功后清空对应草稿。

5. 测试

A1：提交中、成功、普通失败场景通过。
A2：超时与顺序重试通过；旧请求晚到会覆盖重试状态，未通过。
A3：旧请求晚到不再覆盖当前状态，A1、A2 回归通过。
A4：关闭重开保留草稿、成功清空、失败保留及前轮回归通过。

6. 实现 Session 索引

todo.md 格式

T001 标题

Reporter: Human
Status: Open
CurrentAttempt: A1

1. 需求

原始需求描述。

2. 后续调整事件

NULL

3. 验收标准

A1

可检查的完成条件。

4. 方案与代码改动

当前有效方案

简要方案。

A1

方案：本轮的实现方法。

code index

文件
改动简述。

5. 测试

A1：结果简述。

6. 实现 Session 索引

todo.md format

T001 Title

Reporter: Human
Status: Open
CurrentAttempt: A1

1. Requirements

Original requirement description.

2. Follow-up Changes

NULL

3. Acceptance Criteria

A1

Verifiable completion criteria.

4. Approach and Code Changes

Current Valid Approach

Brief approach.

A1

Approach: This attempt's implementation method.

code index

File
Brief change description.

5. Tests

A1: Brief result.

6. Implementation Session Index

todo.md example

T002 Add Feedback Submission State

Reporter: Human
Status: Done
CurrentAttempt: A4

Fictional four-attempt example; code paths, test results and acceptance results are illustrative. Test and Trace links are temporary placeholders.

1. Requirements

Show that feedback is being submitted after the user clicks Submit, so the user is not left unsure whether the action succeeded.

2. Follow-up Changes

A1: Completed button states and success/failure messages. The human added a timeout scenario, requiring that waiting not continue indefinitely. Assigned to A2.
A2: Added a timeout message. Testing found that a late response from an old request overwrites the retry state. Assigned to A3.
A3: Isolated the state of different requests. The human added a requirement to retain unsuccessfully submitted drafts when closing and reopening the form. Assigned to A4.
A4: Added draft retention. Regression testing and human acceptance passed.

3. Acceptance Criteria

A1

Display "Submitting" during submission and prevent repeated clicks.
Show success feedback after success.
Show failure feedback after failure, re-enable the button and retain the input.

A2

If no response arrives within 30 seconds, indicate that the result is not yet confirmed and allow a retry.
Reuse the request key when retrying the same operation to avoid duplicate creation.
A1 criteria still apply.

A3

A late response from an old request must not overwrite the new request's state.
A1 and A2 criteria still apply.

A4

Retain unsuccessfully submitted input when closing and reopening the form within the same page.
Clear the draft after successful submission; recovery after a page refresh is outside this attempt's scope.
A1 through A3 criteria still apply.

4. Approach and Code Changes

Current Valid Approach

Update state by request ID and allow retries with the same request key after a timeout. Store the draft independently of the form and clear it after success.

A1

Approach: Drive the button and result messages through the request lifecycle, retaining input on failure.

code index

src/ui/FeedbackForm.tsx
Switch button text and availability according to request state.
src/ui/submitFeedback.ts
Update submission state and distinguish success from failure.

A2

Approach: Show a timeout message after waiting more than 30 seconds and allow retries; reuse the existing server-side idempotent API.

code index

src/ui/submitFeedback.ts
Add a timeout timer and reuse the same operation's request key on retries.
src/ui/FeedbackForm.tsx
Add timeout text and a retry action.

A3

Approach: Assign each request an ID and allow only the current request to update state.

code index

src/ui/submitFeedback.ts
Check the request ID before callbacks update state and ignore stale callbacks.

A4

Approach: Store the draft in page-level state, retain it when the form closes and clear it after successful submission.

code index

src/ui/feedbackDraft.ts
Store the current page's unsubmitted draft.
src/ui/FeedbackForm.tsx
Restore the draft when opening and synchronize it while editing.
src/ui/submitFeedback.ts
Clear the corresponding draft when the current submission succeeds.

5. Tests

A1: Submitting, success and ordinary failure scenarios passed.
A2: Timeout and sequential retry scenarios passed; a late response from an old request overwrites retry state. Failed.
A3: Late responses from old requests no longer overwrite current state. A1 and A2 regression tests passed.
A4: Draft retention across closing and reopening, clearing on success, retention on failure and earlier regression tests passed.