weichen
001648cd0e
Why: the matrix scoped native work to the pi wrapper's exposed surface; the full-agent batch deliberately expands beyond it, so the new domains need their own acceptance basis recorded (standard conformance + negative tests + product acceptance, not pi comparison) plus honest security boundary notes. Evidence: docs-only change; go vet/test unaffected (verified green in the code commits this branch carries). Impact: docs/parity-matrix.md gains the R15 expansion table mapping every domain to its test evidence; README package table reflects the new runtime/mcp, runtime/skills, runtime/promptx, runtime/subagent packages and the v0.2 exec port. Refs: docs/parity-matrix.md #1-#16 remain valid for wrapper-parity rows.
91 lines
4.6 KiB
Markdown
91 lines
4.6 KiB
Markdown
# Agent-Native
|
||
|
||
独立的 Agent 执行基础仓库：自研执行内核（runtime）、模型与工具能力接入、外部 Agent
|
||
适配器（现有 PI Runner 等），以及共用执行契约与行为验收（conformance）。
|
||
|
||
本仓库是该模块的源码位置。Go 模块路径为 `agent-native`。
|
||
|
||
## 仓库分层
|
||
|
||
| 层 | 职责 | 依赖边界 |
|
||
|---|---|---|
|
||
| contract | 执行契约：Request/Result/Outcome/Error/Capability/Backend/Resolver | 不依赖内核、产品类型、数据库、配置，也不导入错误码库 |
|
||
| exec | 执行端口：Backend/Request/Result/ProcessEvent、预算、步骤重试与失败分类、交付物物化、Stub、并发限流 | 面向调用方的执行端口 |
|
||
| runtime | 多轮循环、工具调度、模型调用、执行会话 | 不导入 Core/Squad；可选使用日志库，nil 日志器不改变结果 |
|
||
| adapters | PI Runner transport / typed-result-v1；native：自研内核 runtime → exec.Backend（规范后端名 agent-native，含会话毒化轮转——resume-unsafe 失败后自动换新会话） | 显式映射外部差异，不伪造缺失能力 |
|
||
| conformance | 所有 Backend 共用的行为验收 | fake 验证契约，真实 adapter 验证能力 |
|
||
|
||
规范后端名：`agent-native`（`pi-native` 为兼容别名，由调用方注册表解析）。
|
||
|
||
## 包
|
||
|
||
| 包 | 内容 |
|
||
|---|---|
|
||
| contract | 四态执行契约 |
|
||
| conformance | 行为验收套件与 fake |
|
||
| exec | Backend/Request/Result/ProcessEvent（v0.2：Model/ToolAllowlist/Skills/Budget/SessionScope/ExecutionID/Env）、Budget、步骤重试与失败分类、交付物物化、Stub、并发限流 |
|
||
| runtime | 多轮循环（预算/取消贯穿、budget_exceeded 事件）、llm、session（compaction/元数据/崩溃安全）、tools（9 内置 + 策略层 Restrict） |
|
||
| runtime/mcp | MCP 客户端（stdio + Streamable HTTP）与 mcp__<server>__<tool> 桥接（server 元数据不可信、上限收敛） |
|
||
| runtime/skills | SKILL.md 技能加载与 load_skill 渐进披露 |
|
||
| runtime/promptx | 系统提示结构化装配（环境事实 + 技能索引 + 交付物约束） |
|
||
| runtime/subagent | 委派端口（Request/Result/Factory）与 delegate_task 工具；嵌套执行由宿主注入 |
|
||
| adapters/native | runtime 作为 exec.Backend，含会话毒化轮转、compaction、技能/搜索/执行/MCP/委派装配（Options 显式注入，未配置不注册） |
|
||
| adapters/pitransport | typed-result-v1 编解码、远程结果解析、Runner 搜索、鉴权头（含 Node 摘要交叉验证测试） |
|
||
|
||
本模块不依赖 Core 或 Squad。上层产品依赖本模块的 contract 与 exec。
|
||
|
||
## 关键语义（详见 contract 包注释）
|
||
|
||
- ExecutionID 一次逻辑执行唯一；重试与受控 fallback 复用。
|
||
- Outcome 四态：Succeeded/Failed/Canceled/Unknown；Unknown 不静默降级。
|
||
- 失败副作用显式分类（none/possible）；possible 禁止无条件重放。
|
||
- 重试单一责任层：步骤级归调用方，传输级有界归 adapter，turn 上限归 runtime。
|
||
- Workspace 路径授权 ≠ OS 沙箱。
|
||
- `contract.ErrorCode` 取值是 `agent.*` 规范码。`ErrorCode()` / `ErrorFields()` 供日志库识别，本包不导入错误码库。
|
||
|
||
## 依赖子模块
|
||
|
||
| 路径 | 作用 |
|
||
|---|---|
|
||
| `deps/development-guidelines` | 开发规范，不参与编译 |
|
||
| `deps/error-code-system` | 规范码目录。`go.mod` 的 `replace` 指向这里 |
|
||
| `deps/logging-system` | 结构化日志。runtime 与 native 适配器可选使用 |
|
||
|
||
版本以本仓 gitlink 为准。`scripts/submodule-consistency.sh` 核对 gitlink 与检出的 HEAD。
|
||
|
||
```bash
|
||
git clone --recurse-submodules ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-Native.git
|
||
# 已克隆时：git submodule update --init --recursive
|
||
```
|
||
|
||
## CodeGraph
|
||
|
||
`codegraph init` 的索引写在 `.codegraph/`。仓库只跟踪 `.codegraph/.gitignore`。SQLite 数据库、WAL、pid、socket 和日志留在本机；根目录 `.gitignore` 与该文件双重忽略，避免索引被提交。
|
||
|
||
## 开发
|
||
|
||
在仓库根目录：
|
||
|
||
```
|
||
go vet ./...
|
||
go test ./...
|
||
```
|
||
|
||
## 依赖本仓库
|
||
|
||
消费方把本仓库当作独立模块。模块路径是短名 `agent-native`，在消费方 `go.mod` 中用 `replace` 指向检出目录：
|
||
|
||
```
|
||
require agent-native v0.0.0
|
||
|
||
replace agent-native => ./deps/agent-native
|
||
```
|
||
|
||
本仓自己的 `go.mod` 则把错误码库和日志库替换到 `./deps/`。消费方若同时依赖这三仓，必须在消费方 `go.mod` 里写自己的 `replace`：依赖模块内部的 `replace` 不会在上层构建中生效。
|
||
|
||
远程：`ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-Native.git`
|
||
|
||
## CI
|
||
|
||
`.gitea/workflows/ci.yml`：go vet + go test（host runner）。
|