DamnatioX Agent

简体中文 · Local-first · Session persistence · Tool runtime

DamnatioX Agent 是终端优先的本地 Coding Agent。当前版本由 Python Harness V2 负责 Session、模型、工具、权限、预算和持久化，由 React + TypeScript + Ink 负责默认全屏终端界面；Rich / prompt-toolkit 界面继续作为兼容入口。

安装

需要 Python 3.14。发布包提供三种常用安装方式：

# 推荐：隔离安装 CLI
pipx install damnatiox-agent

# uv tool
uv tool install damnatiox-agent

# 普通 pip / 虚拟环境
python -m pip install --upgrade damnatiox-agent

Windows 上若 pip 提示用户级 Scripts 目录不在 PATH，执行一次以下命令并 重新打开终端：

$scripts = Join-Path (python -m site --user-base) 'Python314\Scripts'
$path = [Environment]::GetEnvironmentVariable('Path', 'User')
[Environment]::SetEnvironmentVariable('Path', "$path;$scripts", 'User')

默认安装保持 CLI 与 Harness 依赖轻量。需要本地 embedding 模型和语义 知识库工具时，安装 rag extra：

pipx install 'damnatiox-agent[rag]'
# 或
python -m pip install 'damnatiox-agent[rag]'

安装后可在任意已有目录启动：

cd /path/to/project
damnatioX

damnatioX 与 damnatiox 均为正式 CLI 入口。

启动目录就是本次 Agent 的 Workspace；文件工具和命令始终绑定到该目录。 Session、Attempt、Event 与 Artifact 按 Workspace 隔离；Workspace 可写时沿用 <workspace>/.damnatiox，只读目录（例如 C:\Windows\System32）自动使用 ~/.damnatiox/workspaces/<workspace>-<hash>。首次运行会在 React TUI 内显示 DeepSeek API Key 密码输入引导，也可预先设置：

export DEEPSEEK_API_KEY="..."

Windows PowerShell：

$env:DEEPSEEK_API_KEY = "..."

交互式输入的 Key 保存到用户目录 ~/.damnatiox/config.json。首次设置只通过 本机 Node→Python stdio RPC 传递一次，输入全程掩码且服务端不回显；后续启动由 Python gateway 从环境或配置读取。/config 仅显示配置状态和路径。

React gateway 独占 stdin 作为本机 NDJSON 控制通道；Workspace 的 Git 元数据与 Diff 探测使用独立的空输入流，因此从普通目录或非 Git 目录启动也不会阻塞模型 Turn。若升级前已有卡在 Preparing turn 的进程，退出后用新版本重新启动即可。

CLI

damnatiox                         新 Session，默认 --ui auto
damnatiox --continue              恢复当前 Workspace 最近的 Session
damnatiox -c / -continue          上一项的短写与单横线兼容写法
damnatiox -s / -session           打开历史 Session 选择器
damnatiox --resume SESSION_ID     恢复指定 Session
damnatiox --manual-approval       React 界面中在写入与独占工具前显示审批框
damnatiox --ui react              明确使用 React / Ink
damnatiox --ui rich               使用 Rich 兼容界面
damnatiox --ui-info               检查前端 manifest、SHA256 和 Node 运行时
damnatiox --frontend-smoke        无 API Key 前端渲染 smoke
damnatiox --version

--ui auto 优先选择经过 manifest SHA256 校验的 React 前端：

• 平台 wheel 使用包内 Node 24.14.0；
• 通用 wheel 使用系统 Node 22 或更高版本；
• 通用 wheel 找不到兼容 Node 时进入 Rich 界面；
• stdin/stdout 被重定向时，auto 保留 Rich 的线性输入输出路径；
• --ui react 的资源、完整性或运行时错误使用稳定的 DX-UI-* 错误码。

React 启动前不打印 Rich banner，因此 React / Ink 独占 TTY。--ui-info 和 --frontend-smoke 都不读取 API Key。

React / Ink 终端界面

默认界面沿用原 Rich TUI 的信息层次，而不是把 Harness 状态拼成普通日志：

Header
├── Model / reasoning effort / Session / Workspace / Git
Transcript
├── User turn
├── Thinking（可隐藏）
├── ToolActivity（queued / running / approval / result）
└── Assistant response
Composer
├── 支持粘贴与中文 IME 光标定位
└── 输入 `/` 弹出可搜索 slash command / option palette
Approval
├── tool、参数名称与有界脱敏预览
└── Y / N / Esc
Status
└── 动态等待特效、当前阶段、思考/总耗时、Token、诊断

主要快捷键：

Enter          发送
↑ / ↓ / Tab    选择或补全 slash command 与模型等选项
Ctrl+C         中断活动 Turn；空闲时退出
Y / N / Esc    处理当前工具审批
Mouse wheel    每次上下滚动 Transcript 3 行
PageUp/Down    按页浏览 Transcript
Ctrl+Home/End  跳到 Transcript 顶部/尾部
Shift+drag     在鼠标捕获开启时选择终端文字
Ctrl+Shift+V   使用终端原生粘贴；多行内容在输入栏显示为 ↵

界面支持 /help、/status、/tools、/skills、/sessions、/new、 /resume、/history [count]、/context（兼容 /content）、/compact（兼容 /compress）、/config、/diff、/model、/effort、/thinking、/copy、/clear 和 /exit。

输入 / 后，命令面板显示可选命令；/model、/effort、/thinking、 /resume、/history 与 /skills 会继续进入对应选项面板。/model 直接列出 DeepSeek V4 Pro / V4 Flash 及描述，切换结果持久化到 Workspace 运行设置。 Reasoning 流会显示详细内容、实时 Thinking for … 计时和 Braille 等待动画； 最终回答中的 Markdown 表格会按 CJK/emoji 终端 cell 宽度整理为对齐表格。

默认鼠标滚轮由 TUI 捕获，每次滚动三行。Windows Terminal 等终端可按住 Shift 拖选文字；也可执行 /copy 暂停鼠标捕获，使用终端原生选择/复制，再执行一次 /copy 恢复 Transcript 滚轮。输入组件使用 Ink 的真实 cursor API，因此中文 IME 组合文本和候选窗锚定在输入框光标右侧，而不是终端右下角。

前端源码位于 frontend/，生产 bundle 位于 damnatiox_agent/ui/assets/app.mjs。Python launcher 会先校验 assets/manifest.json 中记录的 SHA256，再使用包内或系统 Node 启动它。

完整运行链路

flowchart TD
    CLI["damnatiox：Python CLI launcher"]
    NODE["Node 24 / Node >= 22"]
    REACT["React + TypeScript + Ink TUI"]
    RPC["NDJSON framed JSON-RPC 2.0 over stdio"]
    GW["tui_gateway"]
    API["LocalAgentAPI"]
    APP["AgentApplication"]
    TURN["TurnService"]
    LOOP["AgentLoop"]
    CTX["ContextBuilder / CompletionPolicy / TurnBudget"]
    MODEL["ModelGateway"]
    RUNTIME["ToolRuntime"]
    EXEC["ToolExecutor / Sandbox / ProcessRunner"]
    STORE["Session / Attempt / Event / Artifact Stores"]
    EXT["Skills / Workspace Facts / Attempt Facts"]

    CLI --> NODE
    NODE --> REACT
    REACT <--> RPC
    RPC <--> GW
    GW --> API
    API --> APP
    APP --> TURN
    TURN --> LOOP
    LOOP --> CTX
    LOOP <--> MODEL
    LOOP <--> RUNTIME
    RUNTIME --> EXEC
    TURN <--> STORE
    LOOP --> STORE
    EXT --> CTX

线性表示：

CLI Python launcher
→ Node React/Ink
→ NDJSON JSON-RPC stdio
→ damnatiox_agent.interfaces.tui_gateway
→ LocalAgentAPI / AgentApplication
→ TurnService / AgentLoop
→ ModelGateway / ToolRuntime
→ AgentEvent / Turn result
→ JSON-RPC notification
→ React reducer 与终端组件

Node 前端占用终端 stdin/stdout，并启动独立 Python gateway 子进程。Gateway 的 stdout 只写一行一条的 JSON-RPC；诊断写 stderr。请求读取保留在主线程，Turn 和 Compaction 在 worker 中运行，因此 turn/interrupt 和工具审批在模型或工具运行 期间仍可响应。

RPC 与前后端边界

tui_gateway 只负责协议校验、序列化、worker 调度和进程关闭；模型、工具、 Session 和文件访问仍位于 LocalAgentAPI 与 AgentApplication 后方。

主要 RPC：

initialize 协商 protocol version。缺少凭据时先返回 credentialRequired 和 脱敏配置元数据，React 显示密码输入界面；配置完成后返回 capability、当前 Session 的有界尾部快照、Workspace、模型、reasoning effort、命令表和事件 cursor。更早的 Session 历史使用 session/history 分页读取，界面会显示已省略的 Turn 数量。 Session 元数据持久化创建时间与最后关闭时间；-s/-session 的启动选择器和 /resume 面板都会展示这两个时间。AgentEvent 包含 session_id、 attempt_id、sequence、timestamp、kind、text 和 details；前端按 cursor 去重和恢复，不假定 sequence 连续。

API Key 只在首次 config/setApiKey 的本机 stdio 请求中出现且不进入响应、事件或 日志；OpenAI/DeepSeek client、ToolExecutor 和可变 Session 对象不穿过 RPC。 审批事件仅传工具身份、参数名称与有界脱敏预览；原始完整值留在 ToolRuntime 一侧，EventStore 不持久化该预览。

Harness V2 分层

默认 composition root 是 damnatiox_agent.application.bootstrap.build_agent_application。Router、独立 Planner、LLM Validator、Replanner 和 Answer Repair 仍只存在于 legacy 源码， 不进入默认 React、Rich 或 Python API 热路径。

Agent Loop

核心实现为 damnatiox_agent/agent/loop.py::AgentLoop.run：

while True:
    cancel_token.raise_if_cancelled()
    budget.check()

    context = context_builder.build(session, attempt, tool_registry.schemas())
    context = context_builder.fit_to_budget(
        context,
        budget.remaining_input_tokens,
    )
    response = model_gateway.generate(context, budget, cancel_token)
    attempt.append_assistant_message(response.message)

    if not response.tool_calls:
        completion_policy.validate(response.content, attempt, budget)
        return response.content

    tool_runtime.execute_calls(
        response.tool_calls,
        budget,
        cancel_token,
        tool_result_sink=append_and_checkpoint,
    )

Harness 负责权限、Workspace、预算、timeout、API retry、取消、执行和停止；模型 决定是否调用工具以及收到结果后的下一步。确定性的 schema、路径、退出码和完成 条件由代码判断。

有限默认预算：

模型 SDK 自带 retry 关闭，重试和预算由 ModelGateway 统一控制。 CancellationToken 会停止后续 Loop、关闭 stream，并把取消传播给进程工具； ProcessRunner 负责终止子进程树。

工具、上下文和持久化

ToolRuntime 在现有 ToolExecutor 外统一处理：

1. Tool 注册与 JSON/schema 参数；
2. PermissionPolicy 和 WorkspacePathPolicy；
3. TurnBudget、timeout 与 cancellation；
4. 读并行与写/独占 barrier；
5. ToolResult、Verification、Mutation 和 Artifact 标准化；
6. 每个 barrier 结果立即 checkpoint。

RAG 是模型按需选择的 search_knowledge_base 普通工具，本地 embedding 模型由 damnatiox-agent[rag] extra 提供；read_artifact 对超长 结果执行有界读取。Skills、Workspace Facts 和 Attempt Facts 以 ContextBlock 注入，不在 Loop 内增加路由分支。

Workspace 可写时的状态布局：

.damnatiox/
├── sessions/*.json
├── attempts/<session_id>/<attempt_id>.json
├── events/<session_id>/<attempt_id>.json
├── events/<session_id>/.sequence-high-water
└── artifacts/<session_id>/<attempt_id>/*

只读 Workspace 使用相同子目录结构，根目录切换到 ~/.damnatiox/workspaces/<workspace>-<hash>/；文件工具的 Workspace 边界保持不变。

Turn 开始即保存 running Attempt；assistant message、tool call/result、usage、 verification 和 mutation 按 checkpoint 更新。重启会终态化遗留 Attempt、补齐 terminal event，并恢复 completed Turn。超长 ToolResult 保存为 Artifact，上下文 只携带预览、hash 和引用。

ContextBuilder 估算 system、summary、历史、Skills、工具 schema、当前 ToolResult、Evidence 和工程事实。Compaction 在回答返回后使用独立预算和单 worker 运行，避免阻塞主回答路径。

Python API

不使用 TUI 时可直接嵌入：

import os
from rich.console import Console

from damnatiox_agent.application import build_agent_application
from damnatiox_agent.interfaces import LocalAgentAPI

application = build_agent_application(
    Console(),
    api_key=os.environ["DEEPSEEK_API_KEY"],
    workspace=".",
)
api = LocalAgentAPI(application)
session = api.create_session()
result = api.start_turn(session["session_id"], "检查当前仓库")

React gateway 和 Python 调用方共享同一个 AgentApplication、Attempt 格式与 AgentEvent 协议。

开发、构建与测试

Python：

python -m pip install -e ".[dev]"
python -m ruff format --check .
python -m ruff check .
python -m compileall -q chain context damnatiox_agent rag skill tool tui validation
python -m pytest -q
python -m build
python -m twine check dist/*

React / TypeScript：

cd frontend
npm ci
npm run typecheck
npm test
npm run build
cd ..

damnatiox --ui-info
damnatiox --frontend-smoke

npm run build 使用 esbuild 生成单一 Node ESM bundle 和 SHA256 manifest。 测试覆盖 JSON-RPC、gateway 并发、stream/cancel/approval、React reducer、 slash commands、布局组件、launcher 完整性、Session 恢复和 Harness Loop。 --frontend-smoke 同时验证静态 Ink 渲染和 Node → Python 隔离模式的 initialize / approval / cancel / shutdown 桥接。

Declarative eval：

python -m damnatiox_agent.evals --tasks evals/tasks.json --pretty

默认 eval runner 用 scripted steps 检查 schema、指标和阈值，不代表在线模型质量； AgentApplicationTurnRunner 用于受控的真实 Application 评测。

Wheel 与 GitHub Actions

发布产物分为：

Node 下载 URL、archive SHA256、目标和 wheel tag 固定在 scripts/node-runtime-lock.json。平台构建再次校验 archive，提取 Node executable 与 LICENSE，并将 runtime manifest 写入 wheel；launcher 在执行包内 Node 前校验 executable SHA256。不在源码树中提交 Node 二进制。

.github/workflows/ci.yml 在每次 branch push 及针对 main 的 Pull Request 上，于 Ubuntu、Windows、macOS 使用 Python 3.14 和 Node 24.14.0，执行 npm typecheck/test/build、Ruff、compileall、pytest、Python 构建、Twine 检查，并在干净环境从仓库外目录运行 --version、--ui-info 和 --frontend-smoke。

.github/workflows/publish.yml 继续由 GitHub Release published 触发：

1. 校验 tag 与 Python 包版本；
2. 构建 sdist、通用 wheel 和四个平台 wheel；
3. 对前端、Node archive、wheel 和干净安装执行检查；
4. 汇总并核对发布产物集合；
5. 使用 PyPI Trusted Publishing（OIDC）发布。

Codex / Hermes 的结构借鉴

本项目借鉴的是结构，而非复制实现：

• Codex 的 App Server 思路：前端通过结构化 request/response/notification 与 后端通信，不解析 CLI 文本；
• Codex 的 UI/backend 分工：Session、Turn、权限、工具和持久化归 Harness， TUI 只维护展示与输入状态；
• Hermes 的 facade/gateway 思路：不同入口共享统一 Agent 生命周期和事件；
• 两者共同体现的稳定 ID、事件 cursor、工具审批和前后端协议边界。

DamnatioX 当前仍使用自己的 Python Harness、LocalAgentAPI、NDJSON gateway、 React reducer、Workspace 策略和持久化格式。Rich 兼容层保留用于显式回退； 后续高级能力继续以真实评测和失败案例为前提加入。