meris-agent 0.0.1__tar.gz

meris_agent-0.0.1/.env.example

@@ -0,0 +1,16 @@
+# DeepSeek（OpenAI 兼容）
+# 复制为 .env 并填入真实 key：https://platform.deepseek.com/
+DEEPSEEK_API_KEY=
+MERIS_BASE_URL=https://api.deepseek.com/v1
+MERIS_MODEL=deepseek-chat
+
+# 或使用通用变量名
+# LLM_API_KEY=
+# OPENAI_API_KEY=
+
+# 可选：Anthropic 原生
+# MERIS_PROVIDER=anthropic
+# ANTHROPIC_API_KEY=
+
+# 可选：使用 meris-rs 做 context 压缩（需 meris native build）
+# MERIS_NATIVE=1

meris_agent-0.0.1/.github/workflows/test.yml

@@ -0,0 +1,45 @@
+name: test
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: pip install -e ".[dev]"
+
+      - name: Unit tests
+        run: pytest tests/ -v -m "not integration"
+
+      - name: Ruff check
+        run: ruff check meris tests
+
+  rust:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - name: Cargo test
+        working-directory: meris-rs
+        run: cargo test
+
+      - name: Cargo build release
+        working-directory: meris-rs
+        run: cargo build --release

meris_agent-0.0.1/.gitignore

@@ -0,0 +1,54 @@
+# --- Secrets & local env ---
+.env
+.env.*
+!.env.example
+
+# --- Python ---
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+ENV/
+dist/
+build/
+*.egg-info/
+.eggs/
+pip-wheel-metadata/
+
+# --- Test / lint caches ---
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+
+# --- Rust ---
+meris-rs/target/
+
+# --- IDE / editor (local) ---
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# --- OS ---
+.DS_Store
+Thumbs.db
+Desktop.ini
+
+# --- Meris harness runtime (do not commit) ---
+.meris/sessions/
+.meris/plan/
+.meris/worktrees/
+.meris/spec/
+
+# Commit harness *templates* for this repo: .meris/settings.json, rules/, skills/
+
+# --- Cursor local (not the vscode-meris extension source) ---
+.cursor/

meris_agent-0.0.1/.meris/rules/paths.md

@@ -0,0 +1,6 @@
+# 路径规范（Meris 仓库 cwd）
+
+- Python **包**在 `meris/` 目录：`meris/cli.py`、`meris/harness/`、`meris/tools/`
+- 本仓库 **根目录**文档：`README.md`、`PROGRESS.md`、`AGENTS.md`（不要写成 `meris/README.md`）
+- import 一律 `from meris.xxx import ...`
+- 仅在 **vault 根** cwd、且 Meris 是子目录时，才用 `meris/README.md` 这类带前缀路径

meris_agent-0.0.1/.meris/rules/workspace.md

@@ -0,0 +1,8 @@
+# 工作区 cwd
+
+| 任务 | cwd |
+|------|-----|
+| 改 Meris 代码、README、跑 pytest | Meris **git 仓库根**（clone 后的目录，含 `pyproject.toml`） |
+| 改 Obsidian 笔记 `Articles/` | **vault 根**（Meris 的父目录或独立笔记库） |
+
+Meris 仓库作为 vault 子目录时：在 vault 根跑 `meris run` 改 README 会变成 `meris/README.md` 且可能被 block。**改 Meris 请先 `cd` 到 Meris 仓库根。**

meris_agent-0.0.1/.meris/settings.json

@@ -0,0 +1,38 @@
+{
+  "permissions": {
+    "allow": [
+      "Read",
+      "Edit",
+      "Write",
+      "Glob",
+      "Grep",
+      "Git",
+      "Bash(pytest*)",
+      "Bash(python*)",
+      "Bash(git status*)",
+      "Bash(git diff*)",
+      "Bash(git add*)",
+      "MCP"
+    ],
+    "deny": [
+      "Bash(rm -rf*)",
+      "Bash(git push*)",
+      "Bash(curl*)"
+    ]
+  },
+  "sensors": {
+    "postEdit": ["pytest tests/ -m \"not integration\" -q --tb=no"],
+    "onComplete": true
+  },
+  "context": {
+    "maxMessages": 48,
+    "maxTokens": 32000,
+    "maxToolTokens": 2000
+  },
+  "blockedPaths": ["**/generated/**", "**/node_modules/**"],
+  "hooks": {
+    "preToolUse": [],
+    "postToolUse": []
+  },
+  "mcpServers": {}
+}

meris_agent-0.0.1/.meris/skills/plan-format.md

@@ -0,0 +1,22 @@
+# Skill: Plan 输出格式
+
+## 何时使用
+
+`meris plan`、benchmark plan 任务、用户要求「列计划 / checkbox 任务」时。
+
+## 必须格式
+
+```markdown
+- [ ] 第一条任务
+- [ ] 第二条任务
+- [ ] 第三条任务
+```
+
+- 中括号内**必须有空格**：`- [ ]`（不是 `- []`）
+- 至少 3 条（除非用户指定 N 条）
+- 禁止只用 `1.` `2.` 数字列表
+
+## 路径
+
+- 源码：`meris/cli.py`、`meris/harness/...`
+- 本仓库 README：`README.md`（不是 `meris/README.md`）

meris_agent-0.0.1/AGENTS.md

@@ -0,0 +1,60 @@
+# AGENTS.md — Meris Harness (Instructions subsystem)
+# Inspired by: OpenAI Codex AGENTS.md + Claude Code CLAUDE.md
+
+## 项目说明
+
+- 包管理器：pip（`pyproject.toml` + hatchling）
+- 测试命令：`pytest tests/ -m "not integration"`
+
+## 仓库布局
+
+| 路径 | 说明 |
+|------|------|
+| `README.md` | 仓库根目录说明（**cwd 在本仓库时路径为 `README.md`，不是 `meris/README.md`**） |
+| `meris/cli.py` | CLI 入口 |
+| `meris/loop.py` | Agent 主循环 |
+| `meris/harness/` | Harness 子系统 |
+| `meris/tools/` | 工具注册 |
+| `meris/provider/` | LLM Provider |
+
+计划与代码中的路径、import 一律使用 `meris/` 包前缀（如 `from meris.harness.sessions import ...`）。
+
+## Plan 模式（`meris plan`）
+
+输出 **Markdown 任务清单**，格式必须严格遵守：
+
+- 每条任务一行，使用 **未完成 checkbox**：`- [ ] 描述`（中括号内必须有空格）
+- 至少 3 条 `- [ ]` 任务（用户要求 N 条时按 N 条）
+- 不要用纯数字列表 `1.` 代替 checkbox
+- 文件路径用 `meris/...`（如 `meris/cli.py`），README 在本仓库 cwd 下为 `README.md`
+- 只输出计划，不改代码
+
+示例：
+
+```markdown
+- [ ] 在 meris/harness/sessions.py 添加 prune 函数
+- [ ] 在 meris/cli.py 添加 session prune 子命令
+- [ ] 更新 PROGRESS.md 并跑 pytest
+```
+
+## 代码风格
+- Python 3.11+，ruff line-length 100
+- 最小 diff，匹配现有命名与结构
+
+## 禁止操作
+- 不要修改 `**/generated/**` 下的文件
+- 不要自动 `git push`
+- 不要删除 `migrations/` 下已有 migration
+
+## 会话约定
+- 新会话第一件事：读 `PROGRESS.md`
+- 任务完成或断点变化：更新 `PROGRESS.md`
+- Plan 任务可 `load_skill plan-format`；路径/ cwd 见 `.meris/rules/`
+
+## 完成定义 (Definition of Done)
+
+任务完成 = 以下命令全部退出码为 0：
+
+- `pytest tests/ -m "not integration" -q`
+
+任何一项失败，任务不算完成。

meris_agent-0.0.1/BRAND.md

@@ -0,0 +1,38 @@
+# Meris Agent — 品牌说明
+
+> 正式品牌名：**Meris** · 公开版本 **0.0.1**（首个开源 tag）
+
+## 标识
+
+| 项 | 值 |
+|---|---|
+| **品牌** | **Meris** |
+| **CLI** | `meris` |
+| **Python 包** | `meris-agent` |
+| **Rust 核心** | `meris-rs` |
+| **Harness 目录** | `.meris/` |
+| **环境变量** | `MERIS_*` |
+
+## 定位语
+
+> Harness-first · Model-agnostic · Yours to shape
+
+## 历史
+
+| 日期 | 变更 |
+|------|------|
+| 2026-05 | 正式品牌 **Meris** · 开源发布 **v0.0.1** |
+| 2026-05 | Haltr / forCode 等候选未采用 |
+
+## 新仓库
+
+```bash
+meris init-harness /path/to/repo
+```
+
+Hook 环境变量：`MERIS_TOOL_NAME`、`MERIS_HOOK_PHASE` 等。
+
+## 相关文档
+
+- [docs/LOCAL_SETUP.md](docs/LOCAL_SETUP.md) — 本机扩展与 Rust 配置
+- [docs/RUST_ROADMAP.md](docs/RUST_ROADMAP.md) — Rust 移植路线

meris_agent-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Meris contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

meris_agent-0.0.1/PKG-INFO

@@ -0,0 +1,297 @@
+Metadata-Version: 2.4
+Name: meris-agent
+Version: 0.0.1
+Summary: Model-agnostic coding agent with first-class Harness engineering
+Project-URL: Homepage, https://github.com/meris-agent/meris
+Project-URL: Repository, https://github.com/meris-agent/meris
+Project-URL: Issues, https://github.com/meris-agent/meris/issues
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: openai>=1.40.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40.0; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: full
+Requires-Dist: anthropic>=0.40.0; extra == 'full'
+Requires-Dist: mcp>=1.0.0; extra == 'full'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'full'
+Requires-Dist: pytest>=8.0.0; extra == 'full'
+Requires-Dist: ruff>=0.4.0; extra == 'full'
+Requires-Dist: textual>=1.0.0; extra == 'full'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == 'mcp'
+Provides-Extra: tui
+Requires-Dist: textual>=1.0.0; extra == 'tui'
+Description-Content-Type: text/markdown
+
+# Meris Agent
+
+Model-agnostic terminal coding agent — **Harness-first**, inspired by AtomCode, Claude Code, Codex, Cursor, and Kiro.
+
+## Philosophy
+
+```
+Agent = Model + Harness
+```
+
+- **Built lean** — minimal deps, fast startup (Python MVP → optional Rust later)
+- **Model-agnostic** — OpenAI-compatible API or native Anthropic (`MERIS_PROVIDER=anthropic`)
+- **Yours to shape** — approve mode, PROGRESS checkpoints, interrupt-safe
+- **Harness-first** — AGENTS.md, permissions, hooks, DoD sensors
+
+## Quick start
+
+```bash
+cd meris
+pip install -e .
+
+# Verify installation
+meris version
+
+# Set your model (OpenAI-compatible)
+set OPENAI_API_KEY=sk-...
+set MERIS_BASE_URL=https://api.deepseek.com/v1
+set MERIS_MODEL=deepseek-chat
+
+# Init harness in your project
+meris init-harness /path/to/your/repo
+
+# Ask (read-only)
+meris ask "where is auth handled?"
+
+# Plan (writes tasks, no code)
+meris plan "add rate limiting to /api/users"
+
+# Run agent
+meris run "fix the failing test in tests/test_auth.py"
+
+# Approve mode — confirm each write/edit/bash
+meris run --approve "refactor loop.py"
+
+# Skip DoD sensors
+meris run --no-sensor "explore codebase structure"
+```
+
+## Project layout
+
+```
+meris/
+├── meris/              # Python agent package
+├── meris-rs/           # Rust harness core (P5 MVP)
+├── extensions/
+│   └── vscode-meris/   # VS Code / Cursor plugin
+├── templates/
+└── tests/
+```
+
+## Harness files (in target repo)
+
+| File | Subsystem | From |
+|------|-----------|------|
+| `AGENTS.md` | Instructions | Codex / 新智元 |
+| `.meris/settings.json` | Tools (permissions) | Claude Code |
+| `PROGRESS.md` | State | Anthropic / 新智元 |
+| `.meris/spec/*.md` | Spec workflow | Kiro (optional) |
+
+## Design doc
+
+See `Articles/MyCodingAgent-架构设计.md` in the Obsidian vault.
+
+**Dogfood（7 天）**：见 [docs/DOGFOOD_7DAY.md](docs/DOGFOOD_7DAY.md)
+
+## Roadmap
+
+- [x] P1: Loop + tools + provider + harness loaders
+- [x] P2: Context compression, post-edit sensors, guardrails, git tools, approve mode
+- [x] P3: MCP client, Textual TUI, config-driven hooks
+- [x] P4: Session persistence, parallel sessions, skills, subagent, MCP SSE
+- [x] P5: Rust core MVP (`meris-rs` — context, permissions; full loop still Python)
+
+## Phase D (v0.6.0)
+
+**本机配置（扩展 + Rust）**：见 [docs/LOCAL_SETUP.md](docs/LOCAL_SETUP.md) · Rust 路线见 [docs/RUST_ROADMAP.md](docs/RUST_ROADMAP.md)
+
+一键脚本（Windows）：
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts\setup-local.ps1
+```
+
+**Native Rust core** (`meris-rs/`):
+
+```bash
+meris native build              # requires Rust: https://rustup.rs
+meris native status
+set MERIS_NATIVE=1              # optional native context compression
+meris-rs run doctor             # delegates to Python meris
+```
+
+**Brand**: see [BRAND.md](BRAND.md) — **Meris** (PyPI: `meris-agent`).
+
+**IDE extension** (VS Code / Cursor): `extensions/vscode-meris/` — 安装见 [docs/LOCAL_SETUP.md](docs/LOCAL_SETUP.md)。
+
+## Phase C (v0.5.0)
+
+**Token budget** — `.meris/settings.json`:
+
+```json
+"context": { "maxMessages": 48, "maxTokens": 32000, "maxToolTokens": 2000 }
+```
+
+**Anthropic native**:
+
+```bash
+pip install meris-agent[anthropic]
+set MERIS_PROVIDER=anthropic
+set ANTHROPIC_API_KEY=sk-ant-...
+meris doctor
+```
+
+**Extra tools**: `fetch_url` (HTTP GET), `lint_file` (ruff check).
+
+**MCP resources/prompts**: auto-registered as `mcp_{server}_read_resource` / `mcp_{server}_get_prompt`.
+
+**TUI session panel**: `meris tui` — left sidebar lists sessions; Enter to resume, Ctrl+S refresh.
+
+## Phase A
+
+```bash
+meris doctor                    # env + harness + API probe
+meris plan "add feature"        # saves .meris/plan/tasks.md
+meris run --from-plan "go"      # implement saved plan
+```
+
+See [ROADMAP.md](ROADMAP.md) for full plan.
+
+## Spec workflow (Phase B)
+
+```bash
+meris spec init "rate limiting"
+meris spec status
+meris spec next --note "REST API only"
+meris run --from-spec "implement checklist"
+```
+
+## Event hooks
+
+```json
+{
+  "hooks": {
+    "onSave": [
+      { "matcher": "*.py", "command": "python -m ruff check $MERIS_SAVED_PATH" }
+    ],
+    "onCommit": [
+      { "command": "pytest tests/ -q" }
+    ]
+  }
+}
+```
+
+## Benchmark
+
+```bash
+meris benchmark list
+meris benchmark run
+```
+
+## MCP (external tools)
+
+Configure servers in `.meris/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
+    }
+  }
+}
+```
+
+```bash
+pip install meris-agent[mcp]
+meris mcp list
+```
+
+Tools appear as `mcp_{server}_{tool}` in the agent registry. Resources and prompts are exposed as `mcp_{server}_read_resource` and `mcp_{server}_get_prompt`.
+
+## TUI
+
+```bash
+pip install meris-agent[tui]
+meris tui --cwd . --mode run --approve
+```
+
+Interactive log + task input. Left **Sessions** panel — Enter to resume, Ctrl+R latest, Ctrl+S refresh. Ctrl+L clears log.
+
+## Hooks (settings.json)
+
+Shell hooks run before/after tools (Claude Code–style):
+
+```json
+{
+  "hooks": {
+    "preToolUse": [
+      { "matcher": "bash", "command": "echo pre $MERIS_TOOL_NAME" }
+    ],
+    "postToolUse": [
+      { "matcher": "write_file|edit_file", "command": "echo post" }
+    ]
+  }
+}
+```
+
+Env vars: `MERIS_TOOL_NAME`, `MERIS_TOOL_ARGS`, `MERIS_TOOL_RESULT`, `MERIS_HOOK_PHASE`.
+
+## Sessions (persist & resume)
+
+Every run auto-saves to `.meris/sessions/{id}.json`. Resume after interrupt:
+
+```bash
+meris session list
+meris session show abc123
+meris session resume abc123
+meris run "task" --session-id my-id   # optional fixed id
+```
+
+## Parallel sessions
+
+```bash
+meris parallel "explain auth" "explain db layer" --mode ask -j 2
+meris parallel "fix test A" "fix test B" --mode run --isolate   # git worktree each
+```
+
+## Skills
+
+Place markdown in `.meris/skills/{name}.md`. Agent sees index in prompt; call `load_skill` to fetch full doc.
+
+## Subagent
+
+In `run` mode, agent can call `subagent_run` to delegate read-only exploration with isolated context.
+
+## MCP SSE transport
+
+```json
+{
+  "mcpServers": {
+    "remote": {
+      "transport": "sse",
+      "url": "http://localhost:8080/sse"
+    }
+  }
+}
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

meris_agent-0.0.1/PROGRESS.md

@@ -0,0 +1,58 @@
+# 项目进度
+
+## 已完成
+- [x] P1–P4 + 阶段 A（doctor、permissions、plan、interrupt、git_commit、CI）
+- [x] **阶段 B（v0.4.0）** — spec、session、hooks、benchmark
+- [x] **阶段 C（v0.5.0）** — token 压缩、Anthropic、MCP extras、TUI 面板
+- [x] **阶段 D（v0.6.0）**
+  - [x] D1 `meris-rs` + `meris native`
+  - [x] D2 `BRAND.md`
+  - [x] D3 VS Code/Cursor 扩展
+  - [x] **本机配置**：Cursor 扩展联接 + Rust/MSVC + `meris-rs` release（见 [docs/LOCAL_SETUP.md](docs/LOCAL_SETUP.md)）
+- [x] **品牌 Meris（v0.7.0+）** — CLI / 包 / Harness 统一为 Meris
+- [x] **TUI 提交修复（v0.8.1）** — `_task_busy`；7 天 dogfood 文档
+- [x] **7 天 dogfood Ratchet + 开源整理** — 见下方「Dogfood 复盘」
+- [x] **首个公开版本 v0.0.1** — 对外 tag 从 0.0.1 起计
+
+## 进行中
+- [ ] Benchmark 持续跟踪（`meris benchmark run`）
+- [ ] meris-rs 全量 Agent loop 移植（P5 后续）
+
+## Dogfood 复盘（7 天 · Ratchet）
+
+| # | 错误类型 | 典型表现 | Harness 改动 |
+|---|----------|----------|----------------|
+| 1 | **不知道路径规范** | plan 写 `forge/`；README 写成 `meris/README.md` | `AGENTS.md` 仓库布局 + `.meris/rules/paths.md` |
+| 2 | **输出格式不对** | plan 无 `- [ ]`，benchmark `plan_smoke` fail | `AGENTS.md` Plan 节 + `.meris/skills/plan-format.md` + `benchmark.py` 判题 |
+| 3 | **工作区 cwd 搞错** | 在 vault 根跑 run，README 被 block | `.meris/rules/workspace.md` + vault `AGENTS.md` 双 cwd 表 |
+
+**代码层修复（非 Harness）**：TUI `_task_busy`；context `sanitize_messages_for_api`（tool 消息 400）。
+
+**Meris 比裸 Chat 多什么**：permissions/block、DoD sensor、session 持久化、Plan 落盘、Ratchet 可沉淀规则。
+
+## 阶段 D 命令
+```bash
+# Rust 核心
+meris native status
+meris native build
+set MERIS_NATIVE=1
+meris-rs context compress --max-tokens 3000 < msgs.json
+
+# IDE（见 extensions/vscode-meris/README.md）
+# Command Palette → Meris: Run Agent
+```
+
+## 阶段 C 命令
+```bash
+set MERIS_PROVIDER=anthropic
+pip install meris-agent[anthropic]
+meris tui
+meris mcp list
+```
+
+## 阶段 B 命令
+```bash
+meris spec init "my feature"
+meris benchmark run
+meris session prune --keep 10
+```