Feat/v4 mcp and session store

.github/workflows/ci.yml

@@ -6,8 +6,16 @@ on:
     pull_request:
         branches: [main]
 
+# 同一 PR 只保留最新运行；main 的每次 push 仍独立验证。
+concurrency:
+    group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
+    cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 env:
     CARGO_TERM_COLOR: always
+    # 仅关闭 CI 调试信息，减少编译、链接与缓存开销；保留断言和溢出检查。
+    CARGO_PROFILE_DEV_DEBUG: "0"
+    CARGO_PROFILE_TEST_DEBUG: "0"
 
 jobs:
     build:
@@ -31,24 +39,27 @@ jobs:
             - name: Checkout repository
               uses: actions/checkout@v7
 
+            # 平台无关的源码检查只在 Linux 执行，并在工具链和缓存恢复前快速失败。
+            # §0 依赖方向 CI 门（Seam 3 完整版，PRD 决策 2）：八条边（TUI / ACP
+            # 业务面 / ACP→model / Controller / Runtime / Resources / Middlewares /
+            # Agent）× use 导入 + 全路径引用双模式全校验；豁免清单唯一事实源 =
+            # scripts/import-exemptions.conf。
+            - name: Check §0 layer imports
+              if: runner.os == 'Linux'
+              run: bash scripts/check-layer-imports.sh
+
             - name: Install Rust toolchain
               uses: dtolnay/rust-toolchain@master
               with:
                   toolchain: ${{ matrix.rust }}
                   targets: ${{ matrix.target }}
+                  components: clippy
 
             - name: Cache cargo registry and build
               uses: Swatinem/rust-cache@v2
               with:
                   key: ${{ matrix.target }}
 
-            # §0 依赖方向 CI 门（Seam 3 完整版，PRD 决策 2）：八条边（TUI / ACP
-            # 业务面 / ACP→model / Controller / Runtime / Resources / Middlewares /
-            # Agent）× use 导入 + 全路径引用双模式全校验；豁免清单唯一事实源 =
-            # scripts/import-exemptions.conf。
-            - name: Check §0 layer imports
-              run: bash scripts/check-layer-imports.sh
-
             - name: Build
               run: cargo build --workspace --all-targets
 
@@ -63,10 +74,13 @@ jobs:
               working-directory: npm-packages/@peri-ptc
               run: bun run build
 
-            - name: Run tests
-              run: |
-                  cargo test --workspace --exclude peri-middlewares
-                  cargo test -p peri-middlewares -- --test-threads=1
+            # 分步记录耗时，也确保 Windows 下第一组失败不会被后续成功覆盖。
+            - name: Run workspace tests (excluding middlewares)
+              run: cargo test --workspace --exclude peri-middlewares
+
+            # 涉及进程级全局状态的测试仍须串行执行。
+            - name: Run middleware tests (serial)
+              run: cargo test -p peri-middlewares -- --test-threads=1
 
             - name: Clippy
               run: cargo clippy --workspace --all-targets -- -D warnings

.typos.toml

@@ -9,6 +9,10 @@ fle = "fle"
 gti = "gti"
 bulder = "bulder"
 
+[default.extend-identifiers]
+# 用户已有的环境变量名；只豁免该标识符，不自动改名或屏蔽同类拼写错误。
+TURSO_TOEKN = "TURSO_TOEKN"
+
 [default]
 # commit hash / 十六进制标识符不是拼写错误（如 59ba70b8 中的 ba）
 extend-ignore-re = ["\\b[0-9a-f]{7,40}\\b"]

CLAUDE.md

@@ -1,44 +1,50 @@
-<!--
-ROLE: 设计哲学与任务路由。工程细则 → docs/standards/。
--->
+# CLAUDE.md
 
-# CLAUDE.md — Perihelion
+Peri 是终端 AI 编程助手：用户交付任务，Agent 推进工作，过程可理解、可介入，结果可核对。长期可维护性是设计目标。
 
-Perihelion 是终端 AI 编程助手：用户交付任务，Agent 推进工作，过程可理解、可介入，结果可核对。长期可维护性是设计目标。
+## 项目大目标
 
-## 设计哲学
+v4 目标是存算分离：持久状态、Agent 计算与工具执行环境独立，本地与云端共用核心，分阶段落地。存储后端可配置，Peri 实现持久化；计算核心减少重型依赖，实例可替换、执行可恢复，支持 serverless。Agent 决策、模型推理与工具执行可分开部署。迁移状态以代码、契约测试及 active spec 为准。
 
-- **任务完成与用户控制共同成立。** Agent 主动推进已授权的工作，需要人判断的取舍交还用户。界面优先呈现结果、阻塞和必要决策，过程按需展开；不让用户学习内部编排才能完成任务，不以自动化为由隐藏失败或削弱取消、审批能力。
-- **模型负责判断，系统负责确定性。** 模型输出可以不确定，执行的身份、顺序、权限与终态应可验证。能由类型、协议和状态机保证的约束就在代码落实；不靠提示词弥补执行层缺口，不用重试或兜底把未知状态伪装成成功。
-- **事实与视图分离。** 先确定事实的持有者，再派生模型上下文和界面视图。压缩、缓存和渲染围绕事实构建，不另建可独立漂移的真相。
-- **边界稳定，能力可组合。** 用生命周期和职责决定状态归属，协议、执行、外部能力与界面各守边界。新能力优先接入已有扩展点；不为少写几行跨层直连，不为假想需求预建框架。
-- **成本是设计输入。** 上下文、token、CPU、内存和用户注意力都有限。按需加载、渐进披露，让历史处理、后台任务和缓存的成本有界。性能取舍依据测量，不用数据失真、关键事件丢失或不可恢复状态换取速度。
+1. **Harness**：RCRA（Receive → Compact → Reason → Act）循环执行，hook 扩展生命周期，Middleware 承载业务能力。
+2. **Sessions**：存储会话、消息及执行恢复状态，后端可替换；会话、任务运行与计算实例具有独立生命周期。
+3. **Resources**：文件系统工具、Skill、Cron 等能力经 MCP Middleware 接入；工作区与工具环境可独立于计算实例驻留。
+4. **Orchestration**：基于同构 Agent，管理 Subagent、Multitask 与 Workflow 的任务关系、协调、等待和恢复；Middleware 提供接入，编排生命周期不绑定某个活跃 Harness 实例。
+5. **Endpoint**：ACP 是统一出口协议，stdio 是本地传输方式；传输层可自定义，客户端复用同一业务语义。
 
-理念不代表能力已实现。取舍先守住数据、权限与生命周期契约，再比较交付收益、理解成本和运行成本。
+**内部依赖走 MCP，外部出口走 ACP**：依赖按能力消费方向定义，与部署位置无关；MCP 能力边界不强制对应独立进程，部署隔离按信任边界和生命周期确定。
+
+## 核心工程原则 v1.5
+
+1. **架构与领域优先**：编码前明确目标、领域边界、职责、依赖方向和数据流。复用型抽象等第二个真实用例再提取；协议隔离、依赖反转和确定的可替换边界可在首个用例建立接口，须说明当前需要。
+2. **模块封装复杂度**：接口精简、稳定，文件按职责拆分；规模限制及验证遵循 `STD-SIZE-001`。
+3. **边界与数据流清晰**：协议、领域、持久化与视图模型各守边界；在边界校验和转换，避免跨层共享可变状态。
+4. **保留维护上下文**：记录决策原因、影响与风险，临时方案注明移除条件；技术债务关联任务，关键决策同步文档，不留无上下文的 `TODO`。
+5. **删除优于兼容**：内部重构删除过时实现，不新增兼容层、deprecated shim 或双写；对外兼容义务按协议评估。
+6. **业务规则单一权威**：同一领域规则只维护一份实现；允许多个存储后端和协议 adapter 封装适配差异，共用业务规则与契约。
+7. **优先验证完整行为**：先验证用户可观察的行为，再按风险补齐回归、失败和生命周期测试；遵循 `testing.md`。
 
 ## 行事风格
 
-- **像研究员一样判断，像工程师一样交付。** 区分观察、推断和假设，用代码、复现或实验形成结论。直说理由与局限，不营销、不补造数字，不把计划或命令启动当成完成。
-- **在授权范围内主动闭环。** 常规选择依据仓库证据自行处理；改变用户目标、权限或不可逆结果的歧义及时澄清。不同意方案时说明代价并给出替代方案，不迎合，也不把日常判断推给用户。
-- **改动要小而完整。** 沿因果链修复，覆盖受影响的调用方、契约和文档；不遮盖症状，不混入无关重构。必要重构以减少本次问题的复杂性为界；交付说明改动、验证证据和未验证项。
+- **像研究员一样判断，像工程师一样交付。** 区分观察、推断和假设，以代码、复现或实验支持结论；说明局限，不补造数字，不把命令启动当成完成。
+- **在授权范围内主动闭环。** 依据仓库证据处理常规选择；澄清目标、权限或不可逆结果的歧义。异议须说明代价和替代方案。
+- **改动要小而完整。** 沿因果链覆盖调用方、契约和文档；重构限于本次问题，交付说明改动、验证证据和未验证项。
 
 ## 代码风格的取舍
 
-- **显式表达领域语义。** 命名体现职责，类型表达身份、状态和错误；所有权与副作用沿调用链可见。避免用字符串约定、布尔组合和隐式共享状态承载关键语义。
-- **降低理解成本。** 优先清楚的控制流、小接口和内聚实现；抽象应封装变化，减少调用方的认知负担。少量重复可接受，不为消除重复制造通用层、无语义转发或参数开关集合。
-- **遵循邻近模式，解释必要例外。** 格式、依赖和惯用法沿用已有实践；注释解释不变量、取舍与非显然原因。局部模式违反契约时修正问题，不机械复制。细则见 [rust.md](docs/standards/rust.md)。
+- **显式表达领域语义。** 命名与类型表达职责、身份、状态和错误；所有权和副作用可见，避免字符串约定与隐式共享。
+- **降低理解成本。** 控制流清楚、接口精简；允许少量结构重复，避免制造通用层或参数开关集合。
+- **遵循邻近模式。** 沿用格式和惯用法，注释解释不变量与取舍；违反契约的模式应修正。细则见 [rust.md](docs/standards/rust.md)。
 
 ## 测试风格的取舍
 
-- **测试保护行为和契约。** 按场景断言可观察结果：纯逻辑看输入输出，边界看序列化、错误、顺序与生命周期。内部重构不应迫使无关测试跟着改；不靠复制一遍实现来证明正确。
-- **测试要能揭示目标故障。** 回归测试暴露原问题，并在修复后通过；覆盖相关失败、取消与边界情况。外部不确定性在边界替换，内部关键链路用真实实现；不以全套 mock 自洽推导生产可用。
-- **验证力度随风险扩大。** 从目标测试开始，跨层验证完整链路，进程、恢复或平台承诺验证相应生命周期。测试要确定、隔离、可独立运行；不追求用例数量，不为样板代码制造负担。范围、门禁和证据见 [testing.md](docs/standards/testing.md)。
+- **保护行为和契约。** 按场景断言输入输出、序列化、错误与顺序；避免复制实现或让无关测试耦合内部重构。
+- **揭示目标故障。** 回归测试须暴露原问题，修复后通过；外部不确定性在边界替换，内部关键链路用真实实现。
+- **随风险扩大验证。** 覆盖相关失败、取消、进程恢复和平台生命周期；测试应确定、隔离、可独立运行。范围与证据见 [testing.md](docs/standards/testing.md)。
 
 ## 事实源与任务路由
 
-信息优先级：代码/契约测试 > `docs/standards/` > 模块 `CLAUDE.md` > `docs/design/` > active spec > history。此顺序核对现行行为，不把缺陷当作目标；变更时同步事实源。
-
-先读 [标准索引](docs/standards/index.md)。定位先查 `docs/code-index/`，按意图找主文件、核实入口符号，变更时同步索引。loader 不继承父目录，需显式读取模块指引。
+先读 [标准索引](docs/standards/index.md)，区分现状与目标。按 `docs/code-index/` 核实入口、同步变更。Peri loader 不继承父目录，须显式读取模块指引。
 
 | 任务 | 先读 |
 | --- | --- |
@@ -52,9 +58,9 @@ Perihelion 是终端 AI 编程助手：用户交付任务，Agent 推进工作
 | 文档站 | `peri-cool/CLAUDE.md` + documentation |
 | 历史学习 | `.claude/skills/learn-from-history/SKILL.md` |
 
-简称均指 `docs/standards/`：architecture = `architecture-contracts.md`，其余同名。跨层边界、prompt、事件、工具、中间件顺序或安全变更先读 architecture；Git 操作读 `git.md`，指引维护读 `documentation.md`。
+简称指 `docs/standards/` 同名文件，architecture 指 `architecture-contracts.md`；跨层、prompt、事件、工具、链序或安全变更读 architecture，Git 操作读 `git.md`，指引维护读 `documentation.md`。
 
-设计：`docs/design/README.md`；需求：`spec/issues/`；历史：`spec/global/problems.md`。主路径 `peri-tui → peri-acp → peri-agent::run_react_loop`，退出语义见 Agent 指引；workspace 以 `Cargo.toml` 为准。
+设计：`docs/design/README.md`；需求：`spec/issues/`；历史：`spec/global/problems.md`。主路径 `peri-tui → peri-acp → peri-agent::run_react_loop`；退出语义查 Agent 指引，workspace 查 `Cargo.toml`。
 
 ## Workspace 命令
 
@@ -67,4 +73,4 @@ lefthook run pre-commit
 cargo clippy --workspace --all-targets -- -D warnings
 ```
 
-按变更范围选择命令；改 doc comment 跑 doc tests；E2E 命令见其指引。完成前按 `DOC-UPDATE-001` 核对路由。未经用户要求不 commit。
+按范围选择命令；改 doc comment 跑 doc tests；E2E 查其指引。交付前按 `DOC-UPDATE-001` 核对路由。未经要求不 commit。