中文 | English
一个技能驱动的编程 agent——结构化 harness 约束、可折叠思考的 TUI、crew 编排。基于 langchain + langgraph + Lion-Skills，Windows 优先，跨平台。
一开始只是想花掉阶跃送的 token，顺便走一遍 langchain 全技术栈搭 agent 的流程。框架搭出来之后觉得单纯的 REPL + CLI 不太酷，就开始折腾 TUI 了——目前 TUI 的效果我自己还挺满意的。
不过整体框架并没有细细调优，所以目前只是一个工作之余搓出来的 demo。开源的目的不是做一个产品，而是希望给那些用 langchain 技术栈的人做一点小参考：ReAct 循环怎么搭、harness 怎么做结构约束、TUI 怎么做流式渲染、crew 怎么编排——这些代码都在，能跑，欢迎拿去玩。
关于名字：coderio = code + rio（不是 coder + io 哦）。我的英文名是 Lion，本来想叫 codelion，但感觉怪怪的，所以就叫 coderio 了。
coderio 是一个技能驱动的编程 agent。它的"骨架"是 Lion-Skills 套件（clarify→spec→task→execute→verify→commit 工作流），coderio 给它配上真正能干活的工具、一个强制遵循工作流的 harness 状态控制层，以及交互式 Textual TUI。参照对象是 claude code / codex / zcode。
核心理念：skill 是操作手册，harness 是执行纪律，工具是手。三者分层，互不替代。
- harness 四道门硬约束：agent 写了代码但没运行验证就想说"完成"时，harness 拦截终止、强制续跑——不是提示词软规则，是系统级结构控制（基于工具调用 ground truth）。VerifyGate 解析 bash exit_code，测试失败不再当"验证通过"；GroundingGate 跨 session 记忆已读文件 + 路径归一化（Windows 大小写不敏感）
- 显式状态机：实时推导执行阶段（探索→规划→实现→验证→完成），状态栏显示任务阶段 + 模型活动双轴；每轮的 phase 时间线持久化到 session，可回放调试
- 上下文自动压缩：长会话接近 token 上限时，旧消息自动总结成摘要，保留近期上下文 + tool_call/tool_result 配对完整性，避免超窗失败；空响应时主动压缩再重试（而非无意义重发"请继续"）
- context-rot 自动重启：检测到 agent 陷入工具调用循环或耗尽轮数上限时，从压缩后的干净上下文自动重试一次
- 自动探测上下文窗口：首次配置时自动查询 provider 的
/v1/models/{id}端点探测真实 context window（如 step-3.7-flash 的 256K），持久化到配置——压缩阈值精确匹配实际模型，不再用硬编码默认值 - 意图分类：自动区分 CODE / QA / ANALYZE 三种意图，编码任务走工作流，问答直接答（中英双语信号词）
- 渐进式披露：skill 正文按需加载，系统提示词 ~2K tokens 而非全量堆砌
- 交互式 TUI：Textual 终端 UI，思考折叠（Ctrl+O）、流式输出、工具调用状态栏（动画 spinner + 步骤 + 任务阶段 + 计时器）、slash 命令自动补全、会话恢复选择器
- 两种模式：交互式单 agent（日常）+ 6-agent crew 流水线（大需求，LangGraph 编排）
- 工具错误韧性：工具调用失败变成 tool result 回灌给模型自我修正，不中断 turn
- 工作区沙箱（读写分离）：写工具（write_file/edit_file/multi_edit/bash cwd）路径必须 resolve 在工作区根目录内，超出即硬拒绝；读工具（read_file/grep/glob/list_dir）不受限，agent 可读工作区外的依赖/配置。
--auto模式也执行路径策略——跳过交互确认，不跳过安全边界 - 多 provider + 命名 profile：智谱 GLM / 阶跃 StepFun 的 coding plan（Anthropic 协议）+ OpenAI 兼容；支持多套配置 profile，
/profile运行时切换
方式一：pip 一行安装（推荐，非开发者）
pip install "coderio @ git+https://github.com/Lion-1209/coderio.git"装完直接 coderio 启动。
方式二：下载 Release wheel（离线/内网）
到 Releases 页面 下载最新的 coderio-*.whl，然后：
pip install coderio-0.1.0-py3-none-any.whl方式三：从源码安装（开发者）
git clone https://github.com/Lion-1209/coderio.git
cd coderio
python -m venv .venv
# Windows (Git Bash)
.venv/Scripts/python.exe -m pip install -e ".[dev]"
# Linux / macOS
.venv/bin/python -m pip install -e ".[dev]"要求：Python 3.11+，Windows 上需安装 Git Bash（bash 工具依赖）。
首次运行会触发 onboarding 向导（选 provider、选模型、填 API key），配置自动写入 ~/.coderio/config.toml 和 ~/.coderio/credentials。向导验证 key 时会自动探测模型的上下文窗口大小并持久化，压缩阈值精确匹配实际模型。也可手动配置：
# ~/.coderio/config.toml
[model]
provider_id = "bigmodel_coding_plan" # 智谱/阶跃/OpenAI/Anthropic/Ollama/自定义
default = "glm-5.2"
context_limit = 128000 # （可选）onboarding 自动探测写入，0 = 用下面的默认值
[tools]
permission_mode = "auto" # confirm | plan | auto
workspace_root = "" # 受信工作区根目录（空=用启动目录）；写工具路径必须在此目录内
[context]
enabled = true # 长会话自动压缩（默认开）
trigger_ratio = 0.6 # 达到上下文窗口 60% 时触发
keep_recent = 8 # 保留最近 N 条消息不压缩
model_context_limit = 200000 # fallback：当 profile 未探测到 context_limit 时用支持的 provider：
| provider_id | 说明 | 协议 |
|---|---|---|
bigmodel_coding_plan |
智谱 GLM Coding Plan | Anthropic |
stepfun_coding_plan |
阶跃 StepFun Step Plan | Anthropic |
bigmodel_api / stepfun_api |
智谱/阶跃 API Key 直连 | Anthropic / OpenAI |
openai |
OpenAI 直连 | OpenAI |
anthropic |
Anthropic Claude 直连 | Anthropic |
ollama |
本地 Ollama（无需 key） | OpenAI |
openai_custom |
任意 OpenAI 兼容端点 | OpenAI |
API key 存在 ~/.coderio/credentials（POSIX 0600 / Windows icacls 保护）。
# 交互式 TUI（Ctrl+O 展开思考、可滚动历史、/ 命令自动补全）
coderio
# 或直接（Windows）
.venv/Scripts/python.exe -m coderio.cli.app
# （Linux / macOS）
.venv/bin/python -m coderio.cli.app
# 指定 provider/model
coderio --provider bigmodel_coding_plan --model glm-5.2
# 6-agent crew 流水线（大需求）
coderio crew "实现一个待办事项命令行工具" --auto
# 管理 skill
coderio skills list
coderio skills install进入 TUI 后，输入 / 触发命令自动补全：
| 命令 | 作用 |
|---|---|
/help |
显示所有命令 |
/exit /quit |
退出 |
/config |
查看当前配置（provider/model/mode） |
/mode <confirm|plan|auto> |
切换权限模式 |
/model <name> |
运行时切模型 |
/skills |
列出 skill（★ = 已激活） |
/cost |
查看本次会话 token 用量 |
/clear |
重置上下文（新会话） |
/sessions |
列出最近会话 |
/resume |
恢复历史会话（↑↓ 选择、Enter 恢复、输入过滤） |
直接输入自然语言即可对话或下达编码任务。
分层单体，依赖单向向下：
CLI 层 (cli/) Typer app + Textual TUI + slash 命令
│
Agent 层 (agent/) ReAct 循环 + harness 状态控制 + 提示词构建
│
编排层 (crew/) 6-agent LangGraph StateGraph（可选高级模式）
│
能力层 tools/ · skills/ · llm/ · session/ · config/
| 单 agent（TUI） | crew（流水线） | |
|---|---|---|
| 适用 | 日常交互、问答、编码任务 | 大需求、完整功能开发 |
| agent 数 | 1 个（全工具） | 6 个（每阶段工具物理隔离） |
| harness | 硬约束生效 | 不生效（crew 自有 verify→修复循环） |
| 编排 | ReAct 循环 | LangGraph StateGraph + interrupt |
| 门 | 强度 | 机制 |
|---|---|---|
| VerifyGate | 硬，逐级升级 | 写了代码没跑 bash 就声明"完成"→ 拦截、注入强制续跑；解析 bash exit_code，测试失败（非 0）不算验证通过；2 次后放行 + 红色警告 |
| CompletionGate | 硬 | 有未完成 todo 就声明"完成"→ 拦截 |
| GroundingGate | 硬 | 引用了从未 read_file 的代码位置就声明"完成"→ 拦截（grep/list_dir 不算读内容，防止分析建立在臆测上）；跨 session 记忆已读文件，路径归一化（Loop.py == loop.py） |
| PlanGate | 软提醒 | 没 todo 就写代码 → 工具结果追加 nudge |
长会话最容易遇到的问题就是上下文窗口溢出和 agent"转晕"。coderio 有三层防线：
| 层 | 触发 | 机制 |
|---|---|---|
| 上下文压缩 | input_tokens > 窗口的 60% | 旧消息总结成 system 摘要，保留近期消息 + tool_call 配对完整性 |
| 空响应压缩 | 模型返回空响应（通常上下文过载） | 先压缩上下文再重试，而非无意义重发"请继续" |
| context-rot 检测 | 同一工具调用重复 >3 次 / 达到 max_rounds | 标记为 TurnResult.in_tool_loop / hit_max_rounds |
| 自动重启 | 检测到 context-rot | 从压缩后的干净上下文重跑同一 prompt（最多 1 次） |
agent 执行阶段实时推导并显示在状态栏（步骤3 · [实现] 思考中 · 12.4s）：
探索（read_file/grep）→ 规划（首次 write 无 todo）→ 实现（write + todo）
→ 验证（bash pytest）→ 完成
每轮的 phase 时间线持久化到 session jsonl（kind="phase_timeline"），可回放调试，但对模型不可见（不会污染上下文）。
详细架构设计见 docs/coderio-architecture.md。
# 全量单元测试（~15s）
# Windows (Git Bash):
.venv/Scripts/python.exe -m pytest -q
# Linux / macOS:
.venv/bin/python -m pytest -q
# 按模块
.venv/Scripts/python.exe -m pytest tests/agent/ -v # Windows
.venv/bin/python -m pytest tests/agent/ -v # Linux / macOS
# Live 验证（连真实模型端点，需设置 ANTHROPIC_API_KEY）
ANTHROPIC_API_KEY=<key> .venv/Scripts/python.exe scripts/verify_harness_live.py # Windows
ANTHROPIC_API_KEY=<key> .venv/bin/python scripts/verify_harness_live.py # Linux / macOS三层测试设计：单元测试（逻辑）+ Live 验证（真实集成）+ 手动体验测试。
| 依赖 | 用途 |
|---|---|
| langchain >=0.3 | ReAct agent 基础 |
| langgraph >=0.2 | crew 流水线状态图编排 |
| langchain-anthropic >=0.2 | 智谱/阶跃端点接入（Anthropic 协议） |
| textual >=0.40 | 交互式 TUI |
| rich >=13 | 终端渲染 |
| typer >=0.12 | CLI 框架 |
| deepagents >=0.6 | 实验性 engine（可选：pip install -e ".[deepagent]"） |
src/coderio/
├── agent/ # ReAct 循环、harness、提示词、流式协议
├── cli/ # Typer app、Textual TUI、slash 命令、凭证/onboarding
├── crew/ # 6-agent LangGraph 流水线（orchestrator/agents/state）
├── tools/ # 12 个工具 + 权限门 + langchain 适配
├── skills/ # SkillStore 三层加载 + Lion-Skills 0.3.0（bundled）
├── config/ # 三层 TOML 配置合并
├── session/ # jsonl 会话存储 + resume
└── llm/ # 模型工厂（provider 注册表）
Lion-Skills 作为 bundled skill 随包分发（src/coderio/skills/lion-skills/），无需单独安装。
- deepagents engine 是实验性的：harness 作为 middleware 可用，但默认仍是 ReAct engine。deepagents 已改为可选依赖
- Windows 编码：shell 输出在 GBK locale 下有内置兼容方案
- crew 持久化：当前用内存 MemorySaver（会话内），sqlite 持久化待后续
欢迎贡献！请阅读 CONTRIBUTING.md。
MIT（见 LICENSE）。Bundled Lion-Skills 同为 MIT（见 THIRD_PARTY_LICENSES.md）。