tnega 0.1.0 → 0.3.0

package/README.md

@@ -1,189 +1,115 @@
-# Tnega
-
-Tnega 是 "agent" 的逆写，也是本项目想做的事：把 Agent 本身当作可以被观察、修改、回滚和进化的对象。
-
-Tnega 是一个自研核心的 Agent Harness，参照 DeepSeek Harness 的时空可组合思想，同时把简洁性作为硬约束，并把 Eval 提升为与 Agent Loop、Tools 平级的一等公民。
-
-## 为什么做 Tnega
-
-- Agent = Model + Harness。模型负责思考，Harness 负责模型之外的一切：记忆、工具、权限、执行、评估。
-- 大多数 Harness 是固定系统。Tnega 的目标是让 Harness 本身可以被安全地热插拔和回滚，从而为 Agent 自进化提供基础。
-- dsh 证明了 "一切皆插件" 可以做到，但整个工程很大。Tnega 自研一个语义完整、体积可控的核心，再叠加薄业务层。
-
-## 核心语义
-
-- Context：运行环境与作用域树。服务查找沿父链向上，子 Context 可覆盖服务，隔离通过 scope 实现。
-- Fiber：插件实例的生命周期。状态为 pending / loading / active / failed / unloading / disposed。
-- Effect：每次修改都携带撤销函数，卸载时逆序执行，保证无残留。
-- Event：emit / serial / bail / waterfall 四种派发模式，所有扩展点都是事件。
-
-时空可组合：
-
-- 时间可组合：组件可以热插入、热拔出、热替换，失败可回滚。
-- 空间可组合：依赖齐备才激活，provider 消失时依赖方先停；不同 scope 拥有不同组合。
-
-## 模块规划
-
-| 包 | 职责 |
-| --- | --- |
-| core | Context / Fiber / Effect / Event / Registry / Reflect |
-| agent | 最小 Agent Loop，作为可替换 service |
-| tools | 工具注册与执行管线 |
-| session | JSONL 事件日志，支持 replay / fork / compact |
-| eval | 评测运行时：策略注册、任务执行、证据收集、判分、持久化 |
-| evolve | 进化循环：生成候选、评估、比较、接受或拒绝 |
-| llm | OpenAI 兼容 LLM 适配器，默认对接 OpenCode Go DeepSeek |
-| cli | headless 命令行入口 |
-
-## Eval 是一等公民
-
-Eval 不是测试工具，而是 runtime 的裁判，也是进化的 fitness function。它与 Agent Loop、Tools 平级，共享同一套 Fiber / Effect / Event 机制。
-
-核心对象：
-
-- EvalStrategy：评测策略，以插件形式注册和卸载。
-- Task：任务定义，包含输入、setup、超时与预算。
-- Evidence：不可变证据，由 session log 与 artifacts 组成，可 keyless replay。
-- Verdict：单个策略对单个任务给出的判分结果。
-- EvalRun：一次完整评测，包含候选组件、baseline、verdicts 与 summary。
-
-原则：
-
-- Evidence 是不可变证据：session log + artifacts，重放不需要重新调用模型。
-- Strategy 是插件：可注册、可卸载、可热替换。
-- Run 是隔离实验：候选组件在独立 scope 中加载，跑完自动卸载。
-- Gate 是确定性的：接受或拒绝由阈值、regression、safety 规则决定，而非模型自我评价。
-
-## 自进化
-
-Tnega 把自进化拆成三个可独立验证的阶段：
-
-1. 安全变异：core 的时空语义保证组件可以安全地插入、替换、回滚。
-2. 可靠评估：eval 对候选组件运行同一套任务与策略，产生可比较的分数。
-3. 选择与持久化：通过 gate 的候选成为新 baseline，失败的进入 experiment log。
-
-Experiment log 是一棵树，每个节点包含 candidate、verdicts 与 parent baseline，可回放、可 fork。
-
-evolve 是进化循环本身：`propose` 根据当前 baseline 的诊断结果生成候选，`evaluate` 在 eval 的隔离 scope 中运行候选，`decide` 用可插拔的 gate 比较 baseline 与 candidate，接受后持久化为新 baseline，拒绝后保留旧 baseline。人工审批通过 `evolve/approval-request` 事件暂停，调用方可以异步 approve / reject。
-
-## 与 dsh 的关系
-
-- 理念参照 DeepSeek Harness 与 Cordis 的时空可组合。
-- 核心语义自研，代码自维护，不依赖 Cordis 运行时。
-- 暂时不做：Web UI、子代理、插件市场、生产级沙箱、多模态。
-
-## 路线图
-
-- M1：core 时空语义，插件热重载与回滚。
-- M2：agent loop + tools + session。
-- M3：eval runner 与策略（assert / llm-judge / regression）。
-- M4：evolve 进化循环与 experiment log。
-- M5：真实 LLM 接入与 `tnega run`。
-- M6：时空可组合极端压力测试。
-- M7：真实 LLM 自进化闭环。
-- M8：最小内置工具集与路径沙箱。
-- M9：真实 LLM 工具调用端到端测试。
-- M10：npm / pnpm 发布准备，`tnega` 作为自包含 CLI 包可安装。
-
-## 目录结构（规划）
-
-```text
-packages/
-  core/       # Context, Fiber, Effect, Event, Registry, Reflect
-  agent/      # Agent Loop
-  tools/      # Tool Registry & Execution
-  session/    # JSONL Session Log
-  eval/       # Eval Runtime
-  evolve/     # Evolution Loop
-  llm/        # OpenAI-compatible LLM Adapter
-  cli/        # Headless CLI
-```
-
-## 使用
-
-发布后可通过 npm 或 pnpm 全局安装：
-
-```text
-npm install -g tnega
-pnpm add -g tnega
-tnega run "prompt"
-```
-
-本地开发仍使用 workspace 脚本：
-
-```text
-pnpm tnega run "prompt"            # 运行一次 agent 会话（读取环境变量 key）
-pnpm tnega run --allow-network "fetch https://example.com"
-pnpm tnega run --allow-shell "list files and summarize"
-pnpm tnega eval run tasks.yml      # 运行评测
-pnpm tnega eval compare a b        # 比较两次评测
-pnpm tnega evolve run tasks.yml    # 运行真实 LLM 自进化闭环
-```
-
-不需要 API key 的快速试用：
-
-```text
-pnpm tnega eval run examples/tasks.yml
-```
-
-## 真实 LLM 接入
-
-`tnega run` 通过 OpenAI 兼容协议调用 OpenCode Go 的 DeepSeek 端点，key 只从环境变量读取，不写入代码或仓库文件：
-
-```text
-OPENCODE_GO_API_KEY=sk-xxx pnpm tnega run "Reply with: hello"
-```
-
-也可以使用 `OPENAI_API_KEY` 或 `DEEPSEEK_API_KEY` 作为兼容变量。默认端点为 `https://opencode.ai/zen/go/v1`，默认模型为 `deepseek-v4-flash`；可通过 `OPENCODE_GO_BASE_URL`、`OPENCODE_GO_MODEL` 或 `--base-url`、`--model`、`--max-tokens`、`--temperature` 覆盖。
-
-会话记录默认写入 `.tnega/run.jsonl`，可以使用 `--session <file>` 指定位置。
-
-## 内置工具
-
-`tnega run` 默认挂载一个最小内置工具集，每个工具都是普通 `ToolDefinition`，通过 `builtinTools` 插件注册；插件卸载时工具自动注销，符合“工具也是可插拔”的架构。
-
-默认工具：
-
-```text
-echo, now, calculator, json,
-read_file, write_file, list_dir, glob, grep
-```
-
-高权限工具默认不注册：
-
-- `http_get`：需要 `--allow-network`
-- `shell`：需要 `--allow-shell`，工作目录被限制在 `--cwd` 内
-
-文件工具使用路径沙箱：`read_file / write_file / list_dir / glob / grep / shell` 均被限制在 `--cwd` 内，拒绝绝对路径越界、`..` 越界与 symlink 越界。读取默认上限 256 KiB，写入与搜索默认上限 1 MiB，搜索结果默认 200 条，shell 默认 15 秒超时。
-
-以插件方式接入时，`builtinTools` 接受 `BuiltinToolsConfig`：`cwd / allowNetwork / allowShell / disabled / maxReadBytes / maxWriteBytes / maxSearchBytes / maxResults / timeoutMs`，`disabled` 可进一步关闭任一内置工具。
-
-`tnega evolve run tasks.yml` 把自进化闭环接到真实 LLM：baseline 和候选都由 LLM 驱动，提案规则要求 LLM 返回 JSON 形态的系统提示词候选，评测后由确定性 gate 决定接受或拒绝。实验树默认写入 `.tnega/experiments/log.json`，候选 run 写入 `.tnega/experiments/runs/`，文件中不含 key。
-
-tasks.yml 支持候选声明；没有接入真实 LLM 时可以用内置确定性 loop 跑通完整评测链路：
-
-```yaml
-tasks:
-  - id: echo-good
-    inputText: good
-    assertion:
-      expect: good
-candidates:
-  echo:
-    version: "1"
-    loop: echo
-defaultCandidate: echo
-```
-
-## 状态
-
-- M1 core 时空语义：已完成。Context / Fiber / Effect / Event / Registry / Reflect 已落地，支持插件热插拔、失败回滚、依赖联动与 scope 隔离，配套 94 个 core 测试。
-- M2 agent + tools + session：已完成。SessionLog 以 JSONL 记录可重放的会话事件并支持 fork / compact；ToolsService 提供注册表与可插拔执行管线；AgentService 提供可替换 agentLoop、inbox 与 fake LLM 端到端工具调用，配套 45 个测试。
-- M3 eval 评测运行时：已完成。EvalRunner 在隔离子 Context 中加载候选，逐 task 创建独立会话与工具 scope，支持预算、缓存、持久化与 eval/* 事件；策略 assert / llm-judge / regression / all / weighted / gate 可注册、替换和卸载；CLI 支持 `tnega eval run` 与 `tnega eval compare`，配套 29 个测试。
-- M4 evolve 进化循环：已完成。Candidate / propose / ExperimentLog 树提供候选生成与可回放实验；selection gate 支持 min-score、safety、退化阈值、显著性规则与审批 seam；确定性多轮闭环验证候选失败不影响主 runtime，配套 11 个 evolve 测试。
-- M5 真实 LLM 接入：已完成。`@tnega/llm` 提供 OpenAI 兼容适配器与 `listModels`；`tnega run` 只从环境变量读取 key，支持模型、端点、温度、token 上限与 session 文件参数，配套 OpenAI 协议与 CLI 端到端测试。
-- M6 时空可组合极端压力测试：已完成。新增 10 个压力测试，覆盖 100 次热插拔、20 代 provider 替换、128 插件级联、64 scope 隔离、64 fiber 并发挂载卸载、65 次健康检查拨动与 update 风暴。
-- M7 真实 LLM 自进化闭环：已完成。`evolve run` 用真实 DeepSeek 驱动 baseline、提案与候选评测，gate 选择后持久化实验树；真实端到端实验与记录见 `docs/test/evolve-llm-e2e.md`。
-- M8 最小内置工具集：已完成。`builtinTools` 以插件形式提供 `echo / now / calculator / json / read_file / write_file / list_dir / glob / grep`，`http_get` 与 `shell` 默认关闭，文件与 shell 工具受路径沙箱与字节/结果/超时上限约束；配套 16 个测试。
-- M9 真实 LLM 工具调用端到端测试：已完成。mock 端到端 4 个测试覆盖 calculator / http_get / shell / 路径沙箱；真实 DeepSeek 冒烟 3 个测试覆盖 calculator / read_file / shell，session 记录 tool-call 与 tool-result，测试记录见 `docs/test/tools-llm-e2e.md`。
-- M10 npm / pnpm 发布准备：已完成。`tnega` 根包发布为公共自包含 CLI，`bin` 指向 esbuild 打包的 `dist/bin.js`，`prepublishOnly` 自动构建并跑发布测试；npm 与 pnpm 本地安装验证通过，测试记录见 `docs/test/npm-publish.md`。
+# Tnega
+
+[中文](docs/zh-CN.md)
+
+**Tnega** is "agent" spelled backwards. It is an eval-first agent harness with spacetime-composable plugin lifecycles: components can be hot-swapped and rolled back safely, and Eval is a first-class citizen on par with the agent loop and tools.
+
+## Install
+
+Requires Node.js >= 22.
+
+```bash
+npm install -g tnega
+# or
+pnpm add -g tnega
+```
+
+## Quick Start
+
+```bash
+export OPENCODE_GO_API_KEY=sk-...
+tnega run "Reply with: hello"
+```
+
+`tnega run` uses OpenCode Go's `deepseek-v4-flash` model through the OpenAI compatible endpoint by default. `minimax-m3` is also available through the Anthropic Messages endpoint. The API key can also come from `~/.tnega/config.json` (Windows: `%USERPROFILE%\.tnega\config.json`) with fields `apiKey`, `model`, `baseUrl`, and `temperature`. Precedence: CLI flags > environment variables > config file > defaults.
+
+Run a deterministic eval without an API key:
+
+```bash
+tnega eval run examples/tasks.yml
+```
+
+Start the local web UI:
+
+```bash
+tnega web
+# http://127.0.0.1:3080
+```
+
+The web UI creates sessions as either `general` or `coding` agents. Coding
+sessions support `auto` / `plan` / `execute` modes; plan mode shows the LLM
+generated todo list above the composer and updates each item as tools mark it
+done or failed. `/` slash commands such as `/mode`, `/skills`, and `/mcp` are
+available in coding sessions.
+
+## CLI
+
+```text
+tnega run "prompt"                       # one agent session
+tnega run --allow-shell "list files"     # enable high-permission tools
+tnega web                                # local web UI
+tnega eval run tasks.yml                 # run evals
+tnega eval compare <base> <head>         # compare two eval runs
+tnega evolve run tasks.yml               # run a self-evolution loop
+```
+
+Options include `--model`, `--base-url`, `--max-tokens`, `--temperature`, `--cwd`, `--session`, `--timeout-ms`, `--max-retries`, and `--retry-delay-ms`. Sessions are recorded as JSONL under `.tnega/`.
+
+## Built-in Tools
+
+The default tool set is `echo`, `now`, `calculator`, `json`, `read_file`, `write_file`, `list_dir`, `glob`, and `grep`. High-permission tools are opt-in: `http_get` requires `--allow-network`, `shell` requires `--allow-shell`. File and shell tools are confined to the working directory.
+
+## Coding Agent
+
+`tnega/coding-agent` is a packaged agent plugin for workspace-oriented coding
+sessions. It contributes plan generation, `plan_execute_mark` /
+`plan_execute_result` tools, workspace skills (`skills_list` / `skill_read`),
+stdio MCP servers from `.tnega/mcp.json`, and a slash command registry. The web
+server enables it per session through `agentType: "coding"`, while general
+sessions keep the default loop unchanged.
+
+## Library
+
+Tnega is published as a library as well as a CLI. Use the root package or domain subpaths (`tnega/core`, `tnega/agent`, `tnega/coding-agent`, `tnega/eval`, `tnega/evolve`, `tnega/session`, `tnega/tools`, `tnega/llm`, ...):
+
+```ts
+import { Context, defineAgent, openaiCompatAdapter } from 'tnega'
+
+const root = new Context()
+const fiber = await root.plugin(
+  defineAgent({
+    name: 'coding-agent',
+    version: '0.3.0',
+    system: 'You are a coding agent.',
+  }),
+  { llm: openaiCompatAdapter({ apiKey: process.env.OPENCODE_GO_API_KEY! }) },
+)
+
+const loop = root.get('agentLoop')
+const result = await loop({ text: 'implement the feature' })
+console.log(result.output)
+
+await fiber.dispose()
+```
+
+## Concepts
+
+- **Spacetime composability**: components can be inserted, replaced, and removed at runtime; effects are reversed in order on teardown, so hot-swaps leave no residue.
+- **Eval as infrastructure**: strategies, tasks, evidence, verdicts, and runs are pluggable primitives, and evaluation is also the fitness function for self-evolution.
+- **Self-evolution**: `evolve` proposes candidates, evaluates them in isolated scopes, and accepts or rejects them through deterministic gates.
+
+See the [Chinese guide](docs/zh-CN.md) for the detailed design, model pricing table, library contracts, and roadmap.
+
+## Development
+
+```bash
+pnpm install
+pnpm test
+pnpm typecheck
+pnpm lint
+pnpm build
+```
+
+## License
+
+MIT