docs: 精简 Concept 并对齐 Vein 文档规范

AGENTS.md

@@ -5,7 +5,7 @@
 ## 进入仓库
 
 1. 遵守本文件的全局约束，按 [Agent Wiki 索引](docs/agent-wiki/wiki/index.md) 定位本次任务相关的来源或代码；已知入口时可直接进入。
-2. 需要跨主题理解时选读对应概念页，再按问题追溯来源；不要求每次依次读完 README、概念页和来源。
+2. 需要理解概念及其关系时选读对应概念页，再按问题追溯来源；不要求每次依次读完 README、概念页和来源。
 3. 不熟悉产品、启动方式或支持范围时读 [README.md](README.md)。产品范围以用户已确认的方案为准，代码和测试说明实际能力。
 
 ## 产品与工程边界
@@ -33,8 +33,8 @@
 
 ## 文档维护
 
-- [Agent Wiki 说明](docs/agent-wiki/README.md) 定义维护流程。`sources/` 根目录维护项目级规范与操作说明，`decisions/` 维护当前领域契约与设计取舍，`validation/` 维护验证方法与证据范围；`wiki/index.md` 直接指向来源或代码，`wiki/concepts/` 只按需解释跨主题关系并导航，不重复维护完整规范或验收状态。
-- 影响长期判断时，在同一提交中更新该事实的主要维护位置；只有摘要内容或阅读入口也发生变化时，才同步概念页、索引、本文件或 README。未改变长期知识的小改动不新增文档。
+- [Agent Wiki 说明](docs/agent-wiki/README.md) 定义维护流程。`sources/` 根目录维护项目级规范与操作说明，`decisions/` 维护当前领域契约与设计取舍，`validation/` 维护验证方法与证据范围；`wiki/index.md` 直接指向来源或代码。`wiki/concepts/` 解释概念、关系与职责边界，必要时用简单结构图，并提供带用途的来源链接；具体行为、验证方法和证据由对应来源维护。
+- 影响长期判断时，在同一提交中更新该事实的主要维护位置。概念含义、关系、职责边界或入口变化时才更新概念页；索引、本文件与 README 按各自内容变化更新。精简概念页前先安置独有且有效的规则与证据指针；未改变长期知识的小改动不新增文档。
 - 验收范围扩展、出现阻塞或相关改动影响旧证据时，同步更新证据入口与领域契约中的当前限制；归档前保留从当前来源到相关报告的直接入口。
 - [核心词汇](docs/agent-wiki/sources/product-core-and-glossary.md) 负责产品语义，[协议](docs/agent-wiki/sources/protocol.md) 负责字段与路由；短页面不重复维护完整规范。
 - 旧现场与 main 迁移见 [IMPLEMENTATION.md](IMPLEMENTATION.md)。归档材料只供考据，不能把旧产品边界重新当作当前要求。

docs/agent-wiki/README.md

@@ -1,6 +1,6 @@
 # Team Cross Agent Wiki
 
-这里组织当前工程知识和按需的任务记录，帮助后续工作找到产品约束、相关代码、验证方法及必要的接续信息。`sources/` 与 `wiki/` 描述当前项目，`tasks/` 保存具体工作的过程与证据；任务记录中的临时判断不作为当前项目约束。
+Agent Wiki 为人和 Agent 提供概念关系、当前工程契约与证据入口，帮助后续工作找到产品约束、相关代码、验证方法及必要的接续信息。`sources/` 与 `wiki/` 描述当前项目，`tasks/` 保存具体工作的过程与证据；任务记录中的临时判断不作为当前项目约束。
 
 从 [任务索引](wiki/index.md) 按修改范围选读。产品概览与公共阅读入口见根目录 [README](../../README.md)，用户操作见 [使用指南](../user-guide.md)，本地开发见 [开发与构建](sources/development.md)。
 
@@ -19,7 +19,7 @@ docs/agent-wiki/
 │       └── evidence-map.md          已知验证范围及证据入口
 ├── wiki/
 │   ├── index.md                    工程任务导航
-│   └── concepts/                   按需的跨主题上下文与来源入口
+│   └── concepts/                   概念、关系、职责边界与来源入口
 └── tasks/
     ├── <task-id>.md                 按需创建的活跃任务记录
     └── finished_archived/           已结束记录，默认检索排除
@@ -30,12 +30,20 @@ docs/agent-wiki/
 - `sources/` 根目录维护项目级规范与操作说明，包括词汇、流程、架构、协议、开发、安装与发布；它们不必归入概念或决策目录。每类事实有一个主要维护位置，重要页面开头说明本页职责及相关来源。
 - `sources/decisions/` 维护当前领域契约与设计取舍：规则、适用范围、限制、选择理由和重新评估条件，随所在分支的实现维护。它不是仅保存历史选择的记录库；历史过程留在任务记录。不要求每个领域再拆一份规范或摘要。
 - `sources/validation/` 维护验证方法、通过标准与证据范围。`test-gates.md` 回答如何验证；[evidence-map.md](sources/validation/evidence-map.md) 维护具体路径的已知结果、被测版本/环境、证据指针与适用边界，完整执行结果按 [任务记录](#任务记录) 留存。
-- `wiki/concepts/` 按需解释跨主题的对象关系、容易混淆的边界和阅读顺序，并链接到主要来源与实现。保留理解所需的简短说明，不重复维护完整字段、操作步骤、领域契约或验收状态表。来源已经清楚时，由索引直接链接，不要求来源与概念页一一对应。
+- `wiki/concepts/` 是理解系统的领域地图，按概念关系组织，并用带用途的链接指向主要来源。具体行为、字段、接口、操作步骤和异常处理由来源维护，验证方法与实际结果分别进入验证契约和证据入口。一个概念页可连接多个来源；来源已清楚、无需额外解释时，由索引直接链接。
 - `wiki/index.md` 负责工程任务导航；根目录 [AGENTS.md](../../AGENTS.md) 负责首次进入仓库的阅读顺序和必要行为规则。
 - `tasks/` 保存本次目标、临时判断、执行观察和未完成事项；归档记录只说明当时版本与环境下的判断。
 
 当前采用手工维护，没有启用自动 wiki compiler；未来 compiler 的本地状态使用已被 Git 忽略的 `.llmwiki/`。
 
+## 概念页的抽象边界
+
+概念页保留理解系统所需的对象含义、关系与职责边界。例如“已发布材料固定共享依据，个人会话保留各自上下文，共同执行另有输入归属”说明三者的关系；具体发布条件、投递规则和权限检查回到来源查询。
+
+必要时用简单结构图表达包含、依赖、职责或作用域；连线说明含义，文字应能独立解释同一关系。调用顺序、条件分支和恢复步骤留在对应来源，图与文字采用相同的抽象尺度，无须每页套用固定格式。
+
+仅字段、匹配算法或调用实现变化，而概念关系与来源入口未变时，概念页应仍然成立。改写后用一个关系问题检查解释是否清楚，再用一个具体行为问题检查能否沿链接找到规则；同时核对移出的有效约束与证据指针各有去处。
+
 ## 事实来源
 
 用户已确认的产品决策确定目标；代码和测试说明当前实际能力。二者不一致时，应明确记录差异并修正相关实现或说明，不能把计划写成已经验收。
@@ -49,9 +57,9 @@ docs/agent-wiki/
 ## 更新流程
 
 1. 判断变化是否影响未来任务的产品或工程判断；有影响时更新对应来源，涉及新的取舍时记录原因和重新评估条件。
-2. 只有摘要内容或阅读入口也变化时，才同步相关概念页、任务索引、AGENTS 或 README；不要求每次改动更新所有层级。
+2. 概念含义、关系、职责边界或来源入口变化时才更新概念页；任务索引、AGENTS 与 README 按各自内容变化更新，不机械刷新所有层级。
 3. 按 [验证门槛](sources/validation/test-gates.md) 执行适用检查，将实际结果与未覆盖范围分开记录。新结果扩展范围、暴露阻塞或后续改动影响旧证据时，同步更新证据入口与领域契约中的当前限制；无需给每次普通测试新增条目。
-4. 在同一提交中检查相对链接、代码路径和旧引用。精简概念页前确认规范已由主要来源维护；仅存在于概念页的有效规则先移入对应来源，再改为导航。
+4. 在同一提交中检查相对链接、代码路径、旧引用和索引可达性。精简概念页前核对与来源的差异，将独有且有效的规则、验证要求与证据指针移入对应来源，再移除重复细节。
 
 确定下来的长期知识随开发分支中的代码推进，不集中拖到合入时。恢复既有行为、样式微调等未改变长期知识的工作，不必新增决策或概念页。
 

docs/agent-wiki/sources/architecture.md

@@ -32,13 +32,13 @@ flowchart LR
 
 ## 模块
 
-- `internal/workspace`：Git 预览、干净 worktree、子目录映射、文件读取。
-- `internal/nativecodex`：启动和初始化独立 app-server，通过一个长期 WebSocket 进行 RPC、事件及 server request 分发。
-- `internal/collab`：协作记录、原生协议网关、输入协调、邀请与加入、TUI/Desktop 启动、HTTP 管理接口。
-- `internal/materialstore`：确定性清单、SHA-256 blob、不可变原子写入及内容校验；授权仍由 `internal/collab` 的空间或私有草稿引用决定。
-- `internal/sharing`：`tcx3` 邀请、临时 TLS listener、指纹绑定，以及 LAN / Tailcat 服务端与客户端连接适配。Tailcat 只把虚拟 TCP 443 交给同一 TLS/HTTP 网关。
-- `internal/mcp`：个人辅助 STDIO 与共享运行时批注 STDIO。后者提供当前协作的读取/回复、配对回执、通用空间请求工具及独立凭据，每次调用重新读取 Core 地址，不启动 Core 或复用管理凭据。
-- `packages/web`：新 React/Vite 界面，生产资源编译到 `internal/webassets/dist` 后嵌入 Go 二进制。
+- [internal/workspace](../../../internal/workspace/)：Git 预览、干净 worktree、子目录映射、文件读取。
+- [internal/nativecodex](../../../internal/nativecodex/)：启动和初始化独立 app-server，通过一个长期 WebSocket 进行 RPC、事件及 server request 分发，入口见 [process.go](../../../internal/nativecodex/process.go)。
+- [internal/collab](../../../internal/collab/)：协作记录、原生协议网关、输入协调、邀请与加入、TUI/Desktop 启动、HTTP 管理接口。创建与恢复见 [app.go](../../../internal/collab/app.go)，独立空间、冻结来源与材料版本见 [spaces.go](../../../internal/collab/spaces.go)、[publication.go](../../../internal/collab/publication.go)、[materials.go](../../../internal/collab/materials.go)。
+- [internal/materialstore](../../../internal/materialstore/)：确定性清单、SHA-256 blob、不可变原子写入及内容校验；授权仍由 `internal/collab` 的空间或私有草稿引用决定。
+- [internal/sharing](../../../internal/sharing/)：`tcx3` 邀请、临时 TLS listener、指纹绑定，以及 LAN / Tailcat 服务端与客户端连接适配。Tailcat 只把虚拟 TCP 443 交给同一 TLS/HTTP 网关。
+- [internal/mcp](../../../internal/mcp/)：个人辅助 STDIO 与共享运行时批注 STDIO。后者提供当前协作的读取/回复、配对回执、通用空间请求工具及独立凭据，每次调用重新读取 Core 地址，不启动 Core 或复用管理凭据。
+- [packages/web](../../../packages/web/)：新 React/Vite 界面，生产资源编译到 `internal/webassets/dist` 后嵌入 Go 二进制。
 
 ## 空间工作台
 
@@ -52,7 +52,7 @@ flowchart LR
 
 仅复制 rollout 文件无法替代原生历史数据库。协作记录保存 `sourceId`、已确认的 `sourceTurnId` 和新 `sessionId`。创建调用 `thread/fork`，使用 `lastTurnId` 保留确认过的已完成起点。恢复调用 `thread/resume`，继续同一 ID。
 
-个人 Agent 的当前 Session 分享通过本机持久化请求等待来源本轮完成，不阻塞该 MCP 调用。Codex 原生调用元数据、Claude 的 Session 环境与工具调用历史分别验证来源；独立 Codex 读取进程会重建未结束轮次状态，因此创建前还读取原始 rollout 边界确认完成。工作线程只观察固定轮次；起点漂移、取消或 Core 停止后不自动选新来源或重放。完成后调用既有 Preview/Create/Share；保存部分创建结果，邀请失败可单独恢复。实现见 [current_share.go](../../../internal/collab/current_share.go) 与 [当前 Session 协议](protocol.md#当前-session-与延后分享)。
+个人 Agent 的当前 Session 分享通过本机持久化请求等待来源本轮完成，不阻塞该 MCP 调用。Codex 原生调用元数据、Claude 的 Session 环境与工具调用历史分别验证来源；独立 Codex 读取进程会重建未结束轮次状态，因此创建前还读取原始 rollout 边界确认完成。工作线程只观察固定轮次；起点漂移、取消或 Core 停止后不自动选新来源或重放。完成后调用既有 Preview/Create/Share；保存部分创建结果，邀请失败可单独恢复。实现见 [MCP 当前身份](../../../internal/mcp/current.go)、[延后分享](../../../internal/collab/current_share.go) 与 [来源轮次](../../../internal/nativecodex/source_turn.go)，字段见 [当前 Session 协议](protocol.md#当前-session-与延后分享)。
 
 直接客户端的 `initialize`、会话枚举和请求都经过协作网关。网关只暴露指定协作；固定 `threadId` 与 `cwd`；受限模式固定权限 profile，信任模式沿用原生权限，并允许当前输入者通过原生会话设置选择权限。模型及推理强度继承原生来源和当前输入者的选择。网关与 MCP 共享同一个上游控制连接，避免审批只被某个连接收到而另一入口无法回应。共享仍开放时，直接客户端断开不会终止 app-server。结束共享后，执行、审批、已接收请求和直接连接全部结束才关闭该 Session 的 app-server，释放原生 writer lock；仅 `thread/unsubscribe` 不作为释放依据。关闭过程在会话锁外等待进程退出，恢复等待退出完成，旧进程通知按代次丢弃。
 

docs/agent-wiki/sources/product-core-and-glossary.md

@@ -76,4 +76,4 @@ Codex 的直接操作与本地辅助可使用 TUI 或 Desktop；Claude 实验性
 
 ## 维护入口
 
-字段以 [协作类型](../../../internal/collab/types.go) 和 [接口说明](protocol.md) 为准。修改用词时同步 [用户流程](product-flows.md)、[产品模型任务页](../wiki/concepts/product-model-and-glossary.md) 与面向用户的文案。
+字段以 [协作类型](../../../internal/collab/types.go) 和 [接口说明](protocol.md) 为准。修改用词时核对 [用户流程](product-flows.md) 与面向用户的文案；只有概念含义、关系、职责边界或入口变化时，才更新 [产品模型概念页](../wiki/concepts/product-model-and-glossary.md)。

docs/agent-wiki/sources/product-flows.md

@@ -59,7 +59,7 @@
 
 发起、结束协作均不要求提出问题、生成摘要、收集独立 Evidence 或验证成果。是否提交代码、导出 patch、创建 PR，由用户在自己的开发工具中决定。
 
-用户动作变化时更新本页；只有相关摘要或阅读入口也变化时，才更新概念页或索引，按 [Wiki 更新流程](../README.md#更新流程) 维护。原生客户端的具体版本与已知覆盖范围见 [证据入口](validation/evidence-map.md#原生执行与协作模式)，不能将流程描述本身当作实测结果。
+用户动作变化时更新本页；只有概念关系、职责边界或阅读入口也变化时，才更新概念页或索引，按 [Wiki 更新流程](../README.md#更新流程) 维护。原生客户端的具体版本与已知覆盖范围见 [证据入口](validation/evidence-map.md#原生执行与协作模式)，不能将流程描述本身当作实测结果。
 
 ## 首页与创建入口
 
@@ -122,3 +122,9 @@
 ## 首次体验入口
 
 创建并邀请、邀请确认、上下文优先、输入申请和分发流程见 [分发与首次体验](distribution-and-onboarding.md)。启动不要求 repo；App 与 CLI 复用同一数据目录的 Core。
+
+## 实现入口
+
+- 分享范围、预览与确认：[Publisher](../../../packages/web/src/components/Publisher.tsx)、[PublicationReader](../../../packages/web/src/components/PublicationReader.tsx)。
+- 正文阅读、批注与原文位置：[Reading](../../../packages/web/src/components/Reading.tsx)、[Context](../../../packages/web/src/components/Context.tsx)、[位置映射](../../../packages/web/src/reading.ts)。
+- 首页、语言与主题：[App](../../../packages/web/src/App.tsx)、[i18n](../../../packages/web/src/i18n.ts)、[样式](../../../packages/web/src/styles.css)；主要流程回归见 [flows.test.tsx](../../../packages/web/src/test/flows.test.tsx)。

docs/agent-wiki/sources/protocol.md

@@ -425,6 +425,8 @@ Codex 信任模式支持原生 hook 确认：只含 `hooks.state` 或其子项
 
 批注实现见 [annotation.go](../../../internal/collab/annotation.go)、[上下文组件](../../../packages/web/src/components/Context.tsx) 和 [批注组件](../../../packages/web/src/components/Annotations.tsx)。
 
+Agent 按需读取见 [历史与材料投影](../../../internal/collab/agent_read.go)、[批注读取](../../../internal/collab/agent_annotations.go)；个人管理工具见 [management.go](../../../internal/mcp/management.go)。
+
 路由与转发以 [本机 HTTP](../../../internal/collab/http.go)、[共享连接](../../../internal/collab/network.go)、[原生 RPC](../../../internal/collab/rpc.go)、[邀请与 TLS](../../../internal/sharing/sharing.go) 和 [STDIO MCP](../../../internal/mcp/server.go) 为准。协议变化在同一提交中更新本页及对应测试；Wiki 页面引用本页，不另存一份路由表。
 
 ## 后台控制与错误分类

docs/agent-wiki/sources/validation/test-gates.md

@@ -6,7 +6,7 @@
 
 | 变更范围 | 应完成的检查 |
 | --- | --- |
-| 仅 Markdown、导航或文档迁移 | 相对链接、代码路径、旧引用、索引可达性与 `git diff --check`；不需要启动模型或测试客户端 |
+| 仅 Markdown、导航或文档迁移 | 相对链接、代码路径、旧引用、索引可达性与 `git diff --check`；精简概念页另核对规则与证据指针的去处、关系解释或结构图的含义，以及到具体规则的阅读路径；不需要启动模型或测试客户端 |
 | 产品代码 | 下列 Go 与 Web 工程门槛，按修改范围补相关回归 |
 | Git 预览、目录创建或恢复 | 原目录分支/HEAD/暂存区/文件不变；worktree 不复制四类未提交内容；子目录映射、新会话 ID 与来源关联 |
 | 输入协调、共享或进程生命周期 | 相关 race test，以及直接连接/MCP 共用输入者、重复请求、审批、断线、结束访问和恢复 |