nju-coding-agent-harness 0.1.0__tar.gz

nju_coding_agent_harness-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: nju-coding-agent-harness
+Version: 0.1.0
+Requires-Python: >=3.11
+Requires-Dist: openai
+Requires-Dist: requests
+Requires-Dist: mcp
+Requires-Dist: keyring
+Requires-Dist: httpx
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"

nju_coding_agent_harness-0.1.0/README.md

@@ -0,0 +1,245 @@
+# Coding Agent Harness
+
+一个最小但真实的编码智能体框架（Python 3.11+，Windows/Linux），用 DeepSeek 模型
+（OpenAI 兼容协议）自主完成编码任务，并把**护栏 / 沙箱 / 记忆 / 上下文工程 /
+人机协同 HITL / 反馈闭环**六维度做成透明、可测试的组件。
+
+设计规格见 `docs/superpowers/specs/SPEC.md`（下文以 `§x.y` 引用章节号）；
+每个组件验证了什么理论，见 `docs/COMPONENTS.md`。
+
+## 架构一页图
+
+```
+┌──────────────────────────── 用户（终端） ────────────────────────────┐
+│  python -m harness.main                                            │
+│  main.py  REPL：首次输入即任务 / /命令 / Ctrl+C 菜单 / ask 编号菜单   │
+└───────────────┬──────────────────────────────┬─────────────────────┘
+                │ 任务 / 回答                    │ 流式文本 / 步数统计
+                ▼                               │
+┌──────────────────────────────────────────────▼─────────────────────┐
+│ Agent（agent.py）— 每次任务：检索记忆 → 迭代循环 → 收尾整合           │
+│  每回合：LLM 调用（llm.py，流式、工具调用解析）                      │
+│  └─ 工具流水线（每次工具调用，严格排序，§5.2）：                     │
+│     护栏判定(guardrails.py) → 状态机(state.py) → 钩子(hooks.py)     │
+│     → 执行(sandbox.py) → 钩子 → 结果回灌上下文                       │
+│     其中 ask 判定 → HITL 菜单(main.py) → 自适应策略(policy.py)      │
+└───────┬───────────────────────────┬───────────────┬───────────────┘
+        │                           │               │
+┌───────▼─────────┐   ┌─────────────▼───────┐   ┌───▼──────────────┐
+│ 注册表 registry │   │ 支撑服务             │   │ 持久化（工作区内） │
+│ 内置工具 tools/ │   │ Policy 自适应策略    │   │ memory/*.md 记忆 │
+│ MCP 工具 mcp.py │   │ MemoryStore(TF-IDF) │   │ skills/*/SKILL.md│
+│ 技能 tools/skills│   │ HookBus 转录钩子    │   │ transcripts/*.json│
+│ 子智能体 subagent │   │ StateMachine 状态机 │   │ .env（可选）      │
+└─────────────────┘   └─────────────────────┘   └──────────────────┘
+```
+
+## 快速开始
+
+1. **安装**（PyPI 分发，任选其一）：
+
+   ```bash
+   pip install nju-coding-agent-harness        # PyPI 正式发布
+   pip install -e ".[dev]"                     # 源码分发（项目根目录）
+   ```
+
+2. **配置 API Key**：首次运行时会自动进入配置向导（`getpass` 隐藏输入，
+   保存到系统凭据库）；也可以在 REPL 内用 `/key set` 随时配置（见下文
+   "凭据安全"）。
+
+3. **运行**：
+
+   ```bash
+   python -m harness.main
+   ```
+
+   提示符 `> ` 下直接输入任务（例如"修复 main.py 里的 bug"）；**首次输入
+   （即使以 `/` 开头）一律视为任务**。REPL 顶部 `Ctrl+C` 干净退出并触发
+   SessionEnd 钩子；任务运行中 `Ctrl+C` 弹出暂停菜单（resume / abort）。
+
+## 凭据安全（§4.2 / §7.1）
+
+- **来源优先级**：keyring（Windows Credential Manager，服务名
+  `coding-agent-harness`）→ 环境变量 / `.env` 文件 → 首次运行向导。
+- **首选 keyring**：操作系统加密存储，凭据不出本机。`/key set` 交互录入
+  （隐藏输入）后写入 keyring；`/key clear` 删除；`/key status` 只回显
+  "是否已配置 / 来源 / 验证时间"，**绝不回显明文**。
+- **`.env` 明文风险**：`.env` 文件是本地明文（`DEEPSEEK_API_KEY=...`），
+  且其中的值会进入进程环境、对同一用户的其他进程可见；不要提交进 Git
+  （仓库已通过 `.gitignore` 排除 `.env`，凭据扫描测试
+  `harness/tests/test_security_scan.py` 会检查 key 不落入源码/历史/转录）。
+  使用 `.env` 是备选方案，请确保文件权限收紧。
+- **兜底安全**：key 永不写入日志、转录、记忆或策略文件。
+
+## 代理配置（GitHub / DeepSeek，Windows）
+
+- **DeepSeek API**：默认直连 `https://api.deepseek.com`（HTTPS）。需要
+  代理时，为 `openai`/`httpx` 设置环境变量即可：
+
+  ```powershell
+  $env:HTTPS_PROXY = "http://127.0.0.1:7890"
+  $env:HTTP_PROXY  = "http://127.0.0.1:7890"
+  ```
+
+  （PowerShell 中设置环境变量仅对当前会话有效，不会进入 shell history；
+  请勿用 `export` 方式写入 key，那会进入 shell history。）
+- **GitHub**（克隆仓库、拉取技能时）：给 git 配代理
+
+  ```bash
+  git config --global http.proxy http://127.0.0.1:7890
+  git config --global https.proxy http://127.0.0.1:7890
+  ```
+
+- **Windows 注意**：命令执行基于系统 shell；若在工作区使用 PowerShell
+  脚本或路径含空格/中文，注意引号与编码（项目文件统一 UTF-8）。
+
+## 配置（harness/config.py）
+
+`Config` dataclass 定义全部配置字段（`Config.load(path)` 支持 TOML
+配置文件加载；REPL 启动时使用默认值）：
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `model` | `deepseek-chat` | 模型名 |
+| `base_url` | `https://api.deepseek.com` | OpenAI 兼容端点 |
+| `max_steps` | `50` | 每任务步数上限 |
+| `failure_budget` | `3` | 同类工具连续失败预算（§3.6） |
+| `tool_timeout` | `30` | 工具执行超时（秒） |
+| `memory_top_k` | `2` | 任务启动时检索注入的记忆块数（§3.3） |
+| `max_budget_tokens` | `6000` | 上下文预算，超出先压缩（§3.3） |
+| `compression_keep_turns` | `10` | 压缩保留的最近回合数 |
+| `compression_max_rounds` | `3` | 单任务压缩轮数上限 |
+| `max_output_bytes` | `51200` | 工具输出截断上限 |
+| `workspace` | 当前目录 | 工作区（文件/记忆/技能/转录根） |
+| `mcp_servers` | `[]` | MCP 服务器列表（§5.3） |
+
+## REPL 命令表
+
+实现于 `harness/main.py`（`/help` 输出与之对应）：
+
+| 命令 | 行为 |
+|---|---|
+| `/exit` | 退出 REPL（返回 0） |
+| `/reset` | 重置会话（重建 Agent，清空上下文与状态）；失败打印"重置失败" |
+| `/skills` | 列出工作区 `skills/` 下含 `SKILL.md` 的技能 |
+| `/rules` | 显示策略规则表：`pattern -> action (source)` |
+| `/rules drop skill:<name>` | 移除指定技能注入的规则 |
+| `/key set` | 交互录入 API Key 并保存到 keyring，随后重新初始化会话 |
+| `/key status` | 显示配置状态（是否已配置 / 来源 / 验证时间） |
+| `/key clear` | 清除 keyring 中的 API Key |
+| `/memory` | 列出工作区 `memory/` 下的记忆文件 |
+| `/help` | 命令摘要 |
+
+交互行为（与实现一致）：
+
+- **首次输入即任务**：第一个非空输入（包括以 `/` 开头的字符串）作为任务执行。
+- **任务中 Ctrl+C**：状态机 `interrupt → paused`，弹出编号菜单
+  `1. resume / 2. abort`；EOF 视为 abort。选择 abort → `terminated`；
+  选择 resume → 从暂停处继续（仅允许恢复一次）。
+- **REPL 顶层 Ctrl+C / EOF**：打印换行、触发 SessionEnd 钩子（写转录）后退出。
+- **护栏 ask**：打印 `? 问题` + 编号选项，输入非编号数字重试。
+- **任务收尾**：逐条回显工具调用 `→ name: args`（失败为 `⊘ name: error`），
+  最后打印 `[step N/max | ~T tok]` 步数与近似 token 统计。
+- **流式输出**：模型文本通过 `on_text` 实时打印，无整轮缓冲（§3.1）。
+- **API 失败**（密钥错误 / 限流 / 网络）：打印明确提示，**会话保持存活**，
+  可继续输入任务或 `/key set`。
+
+## 六维度组件（§3）
+
+| 维度 | 组件 | 验证要点（详见 COMPONENTS.md） |
+|---|---|---|
+| 治理护栏 | `guardrails.py` / `policy.py` / `state.py`（§3.4 §11.2 §11.4） | 护栏先行、ask 无超时放行、自适应升降级 |
+| 安全沙箱 | `sandbox.py`（§11.3） | 超时/截断、docker 隔离；**local 非隔离（见下）** |
+| 记忆 | `memory.py`（§3.3） | 纯标准库 TF-IDF、top-k 注入、收尾整合 |
+| 上下文工程 | `agent.py`（预算/压缩）+ `llm.py`（§3.1 §3.3） | 超预算先压缩、保留最近 N 回合、轮数上限 |
+| 人机协同 HITL | `main.py` / `state.py` / `tools/ask.py`（§11.4） | interrupt→paused、awaiting_user 双来源 |
+| 反馈闭环 | `agent.py`（失败预算）（§3.6） | 连续失败 3 次停止、错误回灌可修正 |
+
+配套能力：工具注册表 `registry.py`、内置工具 `tools/`（bash/files/search/web/
+notes/memory/skills/subagent/ask）、MCP 客户端 `mcp.py`、钩子 `hooks.py`、
+转录 `transcript.py`、凭据 `credentials.py`、LLM 客户端 `llm.py`。
+
+## 沙箱非隔离性声明（重要，§11.3）
+
+**`LocalSandbox`（默认后端）不是安全边界**——它在宿主上直接以子进程执行
+shell 命令，隔离由**护栏**（危险模式 deny / ask）与**路径包含性检查**
+（工作区外路径 deny）承担第一道防线。若需要真正的进程/文件系统隔离，
+请配置 **DockerSandbox** 后端。
+
+## Docker 后端（可选，默认 local）
+
+- 通过配置切换沙箱后端；docker 后端用 `docker run --rm` 执行 bash，默认
+  `--network=none`（无网络），以 `-v <workspace>:/workspace` 挂载工作区，
+  容器内无法破坏宿主文件系统、读不到宿主凭据。
+- 镜像默认 `python:3.11-slim`，需预装工具链（python/git 等）。
+- 未安装 Docker 或 daemon 未运行时快速报错，可回退 local。
+- Windows：需 Docker Desktop 并保持运行；挂载路径请使用绝对路径。
+
+## 测试
+
+[![CI](https://github.com/clementineyyy/Coding-Agent-Harness/actions/workflows/ci.yml/badge.svg)](https://github.com/clementineyyy/Coding-Agent-Harness/actions/workflows/ci.yml)
+
+**一键运行**（GitHub Actions CI 与本地使用同一命令）：
+
+```bash
+make test
+```
+
+- `make test` 自动完成：`.venv` 不存在则创建 → `pip install -e ".[dev]"`
+  → `pytest harness/tests -q`（Windows 用 `.venv\Scripts\python.exe`，
+  POSIX 用 `.venv/bin/python`，Makefile 内通过 `$(OS)` 自动判断）。
+- **Windows 无 make** 时的等价命令：
+
+  ```powershell
+  python -m venv .venv
+  .venv\Scripts\python.exe -m pip install -e ".[dev]"
+  .venv\Scripts\python.exe -m pytest harness/tests -q
+  ```
+
+- 只安装不跑测试：`make install`。
+
+### 机制演示（§A.4-D 对齐）
+
+`make demo` 顺序运行三个机制演示脚本（全部退出码 0 即通过）：
+
+1. **demo_1_guardrail_deny** — 护栏拦截危险动作：FakeLLM 请求
+   `rm -rf` / 网络访问等危险动作时，护栏在**执行前**拒绝（deny），
+   绝不让危险命令进入沙箱执行；
+2. **demo_2_feedback_change** — 反馈闭环：工具失败的错误信息回灌
+   上下文后，模型的**下一步动作发生改变**（重试 → 换用替代命令）；
+3. **demo_3_hitl_trace** — HITL 状态机全轨迹确定性复现：
+   `ask → awaiting_user → 执行 → completed` 完整状态迁移。
+
+其中 **demo ③（HITL 状态机全轨迹确定性复现）对应 §A.4-D"主要贡献"
+清单中的重点维度**：以确定性方式复现人机协同的关键状态序列，作为
+该贡献的可运行证据（配合 `test_mechanism_demo.py` 的自动化包装）。
+
+### 离线确定性测试
+
+- 全部测试**无网络依赖、不访问真实 LLM**：由 FakeLLM 客户端与
+  `httpx.MockTransport` 驱动，可离线、确定性复现；MCP 测试使用手写的
+  假 stdio 服务器子进程，不联网。
+- 主要测试文件：
+  `test_agent_core.py` / `test_agent_feedback.py` / `test_agent_context.py` /
+  `test_agent_end.py`（六维度组件单测）、`test_repl.py`（REPL 行为）、
+  `test_acceptance_matrix.py`（验收矩阵，逐条对应 §9）、
+  `test_mechanism_demo.py`（机制演示包装，对应上文 demo ①②③）、
+  `test_llm.py`（LLM 客户端，httpx MockTransport）。
+- 其余覆盖：护栏/状态机/策略/记忆/沙箱/钩子/MCP/凭据扫描
+  （`test_security_scan.py`）/性能冒烟（`test_perf_smoke.py`）/文档一致性
+  （`test_docs.py`）。
+
+## 已知实现偏差（与 spec 附录的差异）
+
+1. 类型定义集中在 `harness/registry.py`（`Context` / `Tool` / `ToolResult`），
+   无独立 `types.py`（`AgentResult` 在 `agent.py`）。
+2. MCP 客户端为手写行式 JSON-RPC 2.0（stdio/url），而非官方 `mcp` SDK
+   （依赖已安装但未使用）——零网络依赖、可确定性测试（§4.3）。
+3. 参数校验为手写轻量 schema 校验（`registry.validate_args`），未引入
+   `jsonschema` 依赖（§3.2）。
+
+## 已知限制
+
+- 平台：Windows 10+ / Linux，Python 3.11+；需 DeepSeek 账号与网络连通。
+- `mcp_servers` 的 stdio/url 服务器需用户自备；连接失败自动停用，不影响其余。
+- Docker 沙箱后端需 Docker Desktop（可选）。

nju_coding_agent_harness-0.1.0/harness/agent.py

@@ -0,0 +1,334 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable
+
+from harness.guardrails import evaluate
+from harness.registry import (
+    Context,
+    ToolResult,
+    build_request_tools,
+    validate_args,
+)
+
+if TYPE_CHECKING:
+    from harness.config import Config
+    from harness.fake_llm import FakeLLM
+    from harness.hooks import HookBus
+    from harness.llm import LLM
+    from harness.memory import MemoryStore
+    from harness.policy import Policy
+    from harness.sandbox import Sandbox
+    from harness.state import StateMachine
+
+SYSTEM_PROMPT = (
+    "你是编码代理助手。可调用工具完成任务："
+    "先规划，再执行，最后给出最终答案。"
+)
+
+_ASK_OPTIONS = ["y", "n", "always_allow", "never_allow"]
+
+
+@dataclass
+class AgentResult:
+    text: str = ""
+    steps_used: int = 0
+    tool_results: list[dict] = field(default_factory=list)
+    policy_changes: list[dict] = field(default_factory=list)
+    messages: list[dict] = field(default_factory=list)
+    failed_sequence: int = 0
+    transcript_path: str | None = None
+
+
+class Agent:
+    def __init__(
+        self,
+        llm: LLM,
+        registry: dict[str, Any],
+        sandbox: Sandbox,
+        hooks: HookBus,
+        policy: Policy,
+        state: StateMachine,
+        memory: MemoryStore | None,
+        config: Config,
+        ask_callback: Callable | None = None,
+        on_text: Callable[[str], None] | None = None,
+    ):
+        self.llm = llm
+        self.registry = registry
+        self.sandbox = sandbox
+        self.hooks = hooks
+        self.policy = policy
+        self.state = state
+        self.memory = memory
+        self.config = config
+        self.ask_callback = ask_callback
+        self.on_text = on_text
+        self._compress_calls = 0
+        self.warnings: list[str] = []
+        self._tool_calls: list[dict] = []
+
+    def context_for_tool(self) -> Context:
+        return Context(
+            workspace=self.config.workspace,
+            sandbox=self.sandbox,
+            hooks=self.hooks,
+            policy=self.policy,
+            state=self.state,
+            memory=self.memory,
+            config=self.config,
+            ask_callback=self.ask_callback,
+            llm=self.llm,
+            registry=self.registry,
+        )
+
+    def pipeline(self, call: dict, ctx: Context) -> ToolResult:
+        name = call["name"]
+        args = call["arguments"]
+        verdict = evaluate(self.policy.rules, name, args)
+        if verdict.action == "deny":
+            return ToolResult(status="error", error=f"guardrail denied: {verdict.reason}")
+        if verdict.action == "ask":
+            self.state.fire("approval_needed", "guardrail")
+            answer = self._ask(verdict.matched_rule, verdict.reason)
+            self.policy.apply_answer(verdict.matched_rule, answer)
+            if self.state.state == "awaiting_user":
+                self.state.fire("user_answered", "user")
+            if answer in ("n", "never_allow"):
+                return ToolResult(status="error", error=f"guardrail denied: {verdict.reason}")
+        if self.state.state == "awaiting_user":
+            self.state.fire("user_answered", "user")
+        args, ok = self.hooks.pre_tool_use(name, args)
+        if not ok:
+            return ToolResult(status="error", error=f"pre_tool_use hook rejected {name}")
+        self.state.fire("tool_requested", "loop")
+        tool = self.registry.get(name)
+        if tool is None:
+            result = ToolResult(status="error", error=f"unknown tool: {name}")
+        else:
+            err = validate_args(tool.parameters, args, self.config.workspace)
+            if err is not None:
+                result = ToolResult(status="error", error=f"参数错误: {err}")
+            else:
+                try:
+                    result = tool.handler(args, ctx)
+                except Exception as exc:
+                    result = ToolResult(
+                        status="error",
+                        error=f"工具 {name} 异常：{type(exc).__name__}: {exc}",
+                    )
+        self.state.fire("tool_finished", "loop")
+        self.hooks.post_tool_use(name, args, result)
+        return result
+
+    def _emit_text(self, text: str) -> None:
+        if text and self.on_text is not None:
+            self.on_text(text)
+
+    def _ask(self, rule, reason: str) -> str:
+        question = f"是否允许执行该操作？\n规则: {rule.pattern}\n原因: {reason}"
+        if self.ask_callback is None:
+            return "n"
+        try:
+            answer = self.ask_callback(question, list(_ASK_OPTIONS))
+        except Exception:
+            return "n"
+        if answer not in _ASK_OPTIONS:
+            return "n"
+        return answer
+
+    def _check_budget(self, messages: list[dict]) -> bool:
+        total = sum(len(m.get("content", "")) / 4 for m in messages)
+        return total > self.config.max_budget_tokens
+
+    def _compress(self, messages: list[dict]) -> list[dict]:
+        keep = self.config.compression_keep_turns
+        oldest = messages[:-keep]
+        if not oldest:
+            return messages
+        self._compress_calls += 1
+        if self._compress_calls > self.config.compression_max_rounds:
+            return self._drop_oldest(messages, keep)
+        try:
+            summary = self.llm.complete(
+                [
+                    {
+                        "role": "system",
+                        "content": (
+                            "请将以下较早回合总结为简洁摘要，"
+                            "保留关键事实、决定与结果："
+                        ),
+                    },
+                    {
+                        "role": "user",
+                        "content": json.dumps(oldest, ensure_ascii=False),
+                    },
+                ],
+                tools=[],
+            )
+        except Exception:
+            return self._drop_oldest(messages, keep)
+        text = (summary.text or "").strip()
+        if not text:
+            return self._drop_oldest(messages, keep)
+        return [{"role": "system", "content": f"[summary] {text}"}] + messages[-keep:]
+
+    def _drop_oldest(self, messages: list[dict], keep: int) -> list[dict]:
+        window = messages[-keep:]
+        if window and window[0]["role"] not in ("user", "system"):
+            for m in reversed(messages[:-keep]):
+                if m["role"] in ("user", "system"):
+                    return [m] + window
+        return window
+
+    def run(self, task: str) -> AgentResult:
+        result = AgentResult()
+        messages = [
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user", "content": task},
+        ]
+        if self.memory is not None:
+            for chunk in self.memory.top_k_chunks(task):
+                messages.append(
+                    {"role": "system", "content": f"[memory] {chunk['chunk']}"}
+                )
+        call_uid = 0
+        fail_seq = 0
+        fail_tool: str | None = None
+        max_fail_seq = 0
+        self._compress_calls = 0
+        self._tool_calls = []
+        self.state.fire("task_submitted", "loop")
+        while result.steps_used < self.config.max_steps:
+            if self._check_budget(messages):
+                messages = self._compress(messages)
+            response = self.llm.complete(messages, build_request_tools(self.registry))
+            result.steps_used += 1
+            if not response.tool_calls:
+                final = response.text or "任务完成"
+                self._emit_text(final)
+                messages.append({"role": "assistant", "content": final})
+                result.text = final
+                return self._finish(result, messages, max_fail_seq)
+            self._emit_text(response.text)
+            assistant_call = []
+            for i, call in enumerate(response.tool_calls):
+                assistant_call.append({
+                    "id": f"call_{call_uid}",
+                    "type": "function",
+                    "function": {
+                        "name": call["name"],
+                        "arguments": json.dumps(call["arguments"], ensure_ascii=False),
+                    },
+                })
+                call_uid += 1
+            messages.append({
+                "role": "assistant",
+                "content": response.text,
+                "tool_calls": assistant_call,
+            })
+            for i, call in enumerate(response.tool_calls):
+                tool_id = f"call_{call_uid - len(response.tool_calls) + i}"
+                tool_result = self.pipeline(call, self.context_for_tool())
+                result.tool_results.append(tool_result)
+                self._tool_calls.append({"name": call["name"], "arguments": call["arguments"]})
+                messages.append({
+                    "role": "tool",
+                    "tool_call_id": tool_id,
+                    "name": call["name"],
+                    "content": json.dumps(
+                        self._result_to_dict(tool_result), ensure_ascii=False
+                    ),
+                })
+                norm = self._result_to_dict(tool_result)
+                failed = norm.get("status") != "success" or bool(norm.get("error"))
+                if failed:
+                    if call["name"] == fail_tool:
+                        fail_seq += 1
+                    else:
+                        fail_seq = 1
+                        fail_tool = call["name"]
+                    max_fail_seq = max(max_fail_seq, fail_seq)
+                    if fail_seq >= self.config.failure_budget:
+                        final = (
+                            f"连续失败 {fail_seq} 次（工具 {fail_tool}），"
+                            f"超过失败预算 {self.config.failure_budget}，停止重试。"
+                        )
+                        self._emit_text(final)
+                        messages.append({"role": "assistant", "content": final})
+                        result.text = final
+                        return self._finish(result, messages, max_fail_seq)
+                else:
+                    fail_seq = 0
+                    fail_tool = None
+        final = f"达到步数上限 {self.config.max_steps}，任务终止，未挂死。"
+        self._emit_text(final)
+        messages.append({"role": "assistant", "content": final})
+        result.text = final
+        return self._finish(result, messages, max_fail_seq)
+
+    def _finish(self, result: AgentResult, messages: list[dict], max_fail_seq: int) -> AgentResult:
+        result.messages = messages
+        self.messages = messages
+        result.failed_sequence = max_fail_seq
+        self.state.fire("final_answer", "loop")
+        self._finalize(result)
+        return result
+
+    def _finalize(self, result: AgentResult) -> None:
+        self.hooks.session_data["tool_calls"] = list(self._tool_calls)
+        self.hooks.session_data["policy_changes"] = self.policy.changes()
+        self.hooks.session_end(self.messages)
+        if self.hooks.transcript_dir is not None:
+            files = [p for p in Path(self.hooks.transcript_dir).glob("*.json")]
+            if files:
+                result.transcript_path = str(
+                    max(files, key=lambda p: p.stat().st_mtime)
+                )
+        if self.memory is not None and self.llm is not None:
+            self._consolidate()
+
+    def _consolidate(self) -> None:
+        try:
+            response = self.llm.complete(
+                [
+                    {
+                        "role": "system",
+                        "content": (
+                            "请总结本次会话的关键事实、决策与工具结果，"
+                            "作为长期记忆保存："
+                        ),
+                    }
+                ]
+                + self.messages,
+                tools=[],
+            )
+        except Exception as exc:
+            self.warnings.append(f"memory consolidation failed: {exc}")
+            return
+        summary = (response.text or "").strip()
+        if not summary:
+            self.warnings.append("memory consolidation skipped: empty summary")
+            return
+        try:
+            self.memory.save(
+                f"session-summary-{datetime.now():%Y%m%d-%H%M%S}", summary
+            )
+        except Exception as exc:
+            self.warnings.append(f"memory save failed: {exc}")
+
+    @staticmethod
+    def _result_to_dict(tool_result) -> dict:
+        if isinstance(tool_result, ToolResult):
+            return {
+                "status": tool_result.status,
+                "output": tool_result.output,
+                "error": tool_result.error,
+                "exit_code": tool_result.exit_code,
+            }
+        if isinstance(tool_result, dict):
+            return tool_result
+        return {"status": "success", "output": str(tool_result)}

nju_coding_agent_harness-0.1.0/harness/config.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import tomllib
+import warnings
+from dataclasses import dataclass, field, fields
+from pathlib import Path
+
+
+@dataclass
+class Config:
+    model: str = "deepseek-chat"
+    base_url: str = "https://api.deepseek.com"
+    max_steps: int = 50
+    failure_budget: int = 3
+    tool_timeout: int = 30
+    memory_top_k: int = 2
+    max_budget_tokens: int = 6000
+    compression_keep_turns: int = 10
+    compression_max_rounds: int = 3
+    workspace: Path = field(default_factory=Path.cwd)
+    max_output_bytes: int = 51200
+    mcp_servers: list[dict] = field(default_factory=list)
+
+    @classmethod
+    def load(cls, path: Path | None = None) -> Config:
+        cfg = cls()
+        if path is None:
+            return cfg
+        path = Path(path)
+        if not path.exists():
+            return cfg
+        try:
+            with path.open("rb") as f:
+                data = tomllib.load(f)
+        except Exception as exc:
+            warnings.warn(f"config 解析失败，使用默认值: {exc}")
+            return cfg
+        known = {f.name for f in fields(cls)}
+        for key, value in data.items():
+            if key not in known:
+                continue
+            if key == "workspace":
+                value = Path(value)
+            setattr(cfg, key, value)
+        return cfg