caigode 0.1.0__tar.gz

caigode-0.1.0/.env.example

@@ -0,0 +1,3 @@
+OPENAI_MODEL=gpt-5.4
+OPENAI_BASE_URL=https://api.openai.com/v1
+OPENAI_API_KEY=sk-xxxx

caigode-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - master
+      - main
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Sync dependencies
+        run: uv sync --dev
+
+      - name: Run tests
+        run: uv run pytest -q

caigode-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,60 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Check distributions
+        run: twine check dist/*
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

caigode-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Codex local runtime
+.codex-home/
+
+# Harness runtime artifacts
+.harness/logs/*.log
+.harness/state/discussion.lock
+.harness/state/last_thread_id.txt
+.harness/state/harness-protected.snapshot
+.harness/state/harness-protect-alert.md
+
+# macOS
+.DS_Store
+
+# pycache
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+
+.caigode/*

caigode-0.1.0/.harness/prompts/discuss.md

@@ -0,0 +1,54 @@
+你现在是“架构优先”的需求澄清代理。先定架构与任务边界，再进入执行。
+
+必须执行的流程（不可跳过）：
+1) 先阅读并更新这些文件：
+   - .harness/state/spec.md
+   - .harness/state/architecture.md
+   - .harness/state/feature_list.json
+   - .harness/state/decisions-needed.md
+2) 先用“选项式问卷”向用户澄清，不接受仅泛泛描述。每次最多问 3 个问题，每个问题都要带候选项与推荐项。
+3) 所有关键问题确认后，再落盘架构与任务树；未确认项必须进入决策门控，不得假设完成。
+
+问卷最小集合（必须覆盖）：
+A. 分层模型（单选）
+- A1: 三层（接口/领域/基础设施）
+- A2: 四层（接口/编排/领域/基础设施）【推荐】
+- A3: 六边形（端口/适配器）
+- A4: 事件驱动（命令/事件/投影）
+B. 模块边界（多选）
+- B1: 入口层（Web/API/CLI/Worker）
+- B2: 应用编排层（UseCase/Service）
+- B3: 领域模型层（Domain/Policy）
+- B4: 数据与集成层（DB/Cache/MQ/Third-party）
+- B5: 运营与质量层（日志/监控/测试/发布）
+C. 数据与状态（单选）
+- C1: 文件状态为主【推荐】
+- C2: SQLite
+- C3: 外部服务
+D. MVP 交付边界（单选）
+- D1: 只做本地可用
+- D2: 本地 + 最小自动化测试【推荐】
+- D3: 本地 + CI
+
+注意：
+- 上述选项是“澄清脚手架”，不是项目类型假设。
+- 不要把用户项目默认成 coding agent、CLI 工具或特定技术栈。
+
+落盘要求：
+1) .harness/state/spec.md：写清问题、目标、约束、非目标、MVP 验收标准（可量化）。
+2) .harness/state/architecture.md：按文件模板补齐层职责、模块边界、依赖约束、状态策略、风险边界。
+3) .harness/state/feature_list.json：必须是“L1 能力组 + L2 可执行任务”混合数组。
+
+L2 任务硬约束（每条都必须满足）：
+- kind 必须是 workitem，level 必须是 L2。
+- title 必须包含 动词 + 对象 + 位置（文件或模块）。
+- entrypoints/changed_files 至少各 1 项，且可定位。
+- implementation_steps 必须是 3~7 条可执行步骤。
+- verification 必须给出可执行命令与预期信号。
+- session_budget 必须为 1（单次会话可完成）。
+- status 初始为 todo，passes 初始为 false。
+
+如果信息不足或冲突：
+- 将 .harness/state/decisions-needed.md 写成 status: pending
+- items 中写 question/options/recommendation
+- 输出 DECISION_REQUIRED 并停止，不进入实现阶段

caigode-0.1.0/.harness/prompts/run.md

@@ -0,0 +1,36 @@
+你现在是连续执行代理。目标是“一轮只完成一个 L2 任务并提交”。
+
+1) 先阅读这些文件：
+   - .harness/state/spec.md
+   - .harness/state/architecture.md
+   - .harness/state/feature_list.json
+   - .harness/state/codex-progress.md
+   - .harness/state/decisions-needed.md
+   - git log --oneline -n 20
+
+2) 只允许选择一个 kind=workitem 且 level=L2 且 status=todo 的任务执行，并满足：
+   - depends_on 里的任务都已 done
+   - session_budget=1
+   - changed_files 与 entrypoints 清晰可定位
+3) 先输出本轮执行计划：目标任务 ID、涉及文件、验证命令。计划不清楚则先补全任务定义，不能硬做。
+4) 仅实现该 L2 任务范围内改动，不扩散到无关任务。
+5) 完成后执行该任务 verification 中定义的命令，并记录结果。
+6) 验证通过后，必须执行 git add -A 和 git commit。
+   - 提交信息格式：feat(<task-id>): <task-title>
+   - 非新功能可用 fix/chore，但必须包含 task-id
+7) 仅在“验证通过 + commit 成功”后，将该任务 status=done 且 passes=true。
+8) 更新 .harness/state/codex-progress.md，记录：任务 ID、改动文件、验证命令与结果、提交哈希、下一步、阻塞点。
+9) 如果任务未完成，不允许在原地空转：
+   - 若是定义不清：先修正该任务字段（entrypoints/steps/verification）
+   - 若是任务过大：拆成 2~4 个新的 L2 任务，并把原任务 status=blocked，notes 写明拆分原因
+   - 禁止连续两轮在同一未完成任务上重复相同尝试
+10) 如果需要人类决策：
+   - 将 .harness/state/decisions-needed.md 写成 status: pending
+   - 在 items 下列出决策问题、可选项、推荐项
+   - 输出标记词 DECISION_REQUIRED
+   - 本轮停止继续实现，等待人类输入
+11) 不要预设项目类型（如 agent/CLI/Web/数据平台 等），执行内容必须以 spec/architecture/feature_list 的已确认信息为准。
+12) 不要修改以下 harness 文件：
+   - codex.sh
+   - .harness/prompts/discuss.md
+   - .harness/prompts/run.md

caigode-0.1.0/.harness/state/architecture.md

@@ -0,0 +1,110 @@
+# Architecture Contract
+
+## 1) 业务分层（必填）
+- 采用分层：
+  - A1 三层：接口层 / 领域层 / 基础设施层。
+- 层与职责：
+  - L-Interface:
+    - 承接多子命令 CLI 入口、REPL 会话循环、参数解析、用户交互输出。
+    - 承接 B2 应用编排模块，负责将一次用户输入编排为领域决策、模型调用、工具执行和状态落盘。
+    - 计划中的主要模块：`src/caigode/cli.py`、`src/caigode/interface/repl.py`、`src/caigode/interface/handlers/`、`src/caigode/application/`。
+  - L-Orchestration:
+    - 本项目不设独立编排层。
+    - B2 以逻辑模块形式存在于接口层内部的 `application` 包中，避免与 A1 冲突。
+  - L-Domain:
+    - 定义会话、消息、任务计划、工作项、工具调用、验证结果、交付产物等核心对象。
+    - 定义规则：状态转移、工具权限、验证结论、交付材料拼装规则。
+    - 计划中的主要模块：`src/caigode/domain/session.py`、`src/caigode/domain/task.py`、`src/caigode/domain/policies.py`.
+  - L-Infra:
+    - 提供 OpenAI 兼容 API 客户端、文件状态仓储、工作区文件读写、shell 执行、git 信息采集、日志与测试支撑。
+    - 计划中的主要模块：`src/caigode/infra/openai_client.py`、`src/caigode/infra/state_store.py`、`src/caigode/infra/workspace.py`、`src/caigode/infra/shell.py`、`src/caigode/infra/review_artifacts.py`.
+
+## 2) 模块边界（必填）
+- 模块清单：
+  - B1 入口层：CLI 子命令、参数与交互适配。
+  - B2 应用编排层：聊天会话服务、单次运行服务、状态查询服务、交付摘要服务。
+  - B3 领域模型层：会话状态、消息、工具调用、验证报告、交付材料等对象与策略。
+  - B4 数据与集成层：OpenAI 兼容 API、文件状态存储、工作区访问、shell、git。
+  - B5 运营与质量层：日志、夹具、自动化测试、开发文档。
+- 入口文件/命令：
+  - 产品入口不使用 `codex.sh`。
+  - 新产品入口定义为 Python CLI：
+    - `uv run python -m caigode.cli chat`
+    - `uv run python -m caigode.cli run`
+    - `uv run python -m caigode.cli status`
+    - `uv run python -m caigode.cli review`
+  - 后续如提供可执行脚本，统一指向 `src/caigode/cli.py`。
+- 模块依赖约束（谁可以依赖谁）：
+  - 接口层可依赖领域层和基础设施层暴露的抽象与适配器。
+  - 接口层中的 `application` 编排模块可以组合领域对象与基础设施服务，但不得把基础设施细节泄漏给领域层。
+  - 领域层不得依赖 CLI、HTTP、文件系统、shell 或 git 具体实现。
+  - 基础设施层不得承载业务策略，只实现端点访问、状态读写和外部副作用。
+  - 运营与质量层可引用任意层进行测试和观测，但不反向参与运行时领域决策。
+
+## 3) 数据与状态（必填）
+- 核心数据对象：
+  - `AgentConfig`：模型、URL、API Key、工作区、会话目录、默认验证命令。
+  - `SessionState`：会话 ID、当前模式、消息历史、计划、最近动作、错误状态。
+  - `TaskIntent`：用户任务、约束、目标文件、交付要求。
+  - `ToolAction`：文件读取、文件修改、shell 执行、git 摘要、review 产物写入。
+  - `VerificationResult`：命令、退出码、摘要、时间戳。
+  - `ReviewArtifact`：变更摘要、验证摘要、提交说明草稿、后续风险。
+- 持久化策略：
+  - C1 文件状态为主。
+  - 运行时状态写入工作区内 `.caigode/` 目录。
+  - Python 依赖、锁文件与脚本执行由 `uv` 管理，锁文件应纳入仓库。
+  - 推荐文件布局：
+    - `pyproject.toml`
+    - `uv.lock`
+    - `.caigode/config.snapshot.json`
+    - `.caigode/sessions/<session-id>.json`
+    - `.caigode/logs/<session-id>.log`
+    - `.caigode/artifacts/<session-id>-review.md`
+    - `.caigode/artifacts/<session-id>-commit.txt`
+- 状态一致性与回滚策略：
+  - 状态文件采用“临时文件写入 + 原子替换”策略。
+  - 文件修改前后均记录摘要；失败命令不回滚工作区，但必须记录到会话状态与日志。
+  - 对高风险 shell 指令和批量文件改动，接口层应要求显式确认或启用安全策略。
+
+## 4) 外部集成（可选）
+- 第三方服务：
+  - 唯一批准的外部网络集成是 OpenAI 兼容 API 端点。
+  - API 端点必须支持自定义 `base_url`、`model` 和鉴权信息。
+  - 不把 `codex` CLI 作为模型引擎依赖。
+- 失败与重试策略：
+  - 模型请求失败时保留原始错误上下文，并返回可读诊断。
+  - 对网络超时、429、5xx 可配置有限重试；默认重试次数应保守。
+  - 本地命令执行只按退出码判定成功与否，不做隐式重放。
+
+## 5) 非功能性要求（必填）
+- 性能：
+  - 目标为单用户本地使用，不追求高并发。
+  - CLI 冷启动应仅完成配置装载与必要初始化，避免非必要扫描全仓库。
+- 稳定性：
+  - 任一子命令失败时返回非零退出码，并在日志或终端给出可定位原因。
+  - 最小自动化测试至少覆盖配置装载、CLI 入口、会话状态持久化、模型客户端适配和 review 产物输出。
+  - 本地开发、测试与运行命令统一通过 `uv run` 执行，避免环境漂移。
+- 安全与高风险操作边界：
+  - shell 执行范围限制在用户指定工作区。
+  - 不默认允许跨工作区写入、系统级目录写入或任意外部服务访问。
+  - API Key 不写入 review 产物与普通日志；如需快照，仅保留脱敏信息。
+- 可观测性（日志/指标）：
+  - 运行日志写入 `.caigode/logs/`。
+  - `status` 子命令应能读取最近会话状态、最近验证结果与最近错误。
+  - MVP 不强制引入指标平台，但日志字段需要支撑问题定位。
+
+## 6) 实施边界（必填）
+- 本轮实现范围（In）：
+  - 新建独立 Python 项目骨架与多子命令 CLI。
+  - 建立基于 `uv` 的依赖管理、锁文件与执行命令约定。
+  - 实现交互式会话主路径、文件状态持久化、OpenAI 兼容 API 客户端、本地工具适配。
+  - 实现最小 review/交付材料输出。
+  - 编写本地最小自动化测试。
+- 明确不做（Out）：
+  - 改写 `codex.sh` 成为产品主入口。
+  - 接入数据库、浏览器自动化、远程 CI 托管、插件系统、多代理协作。
+  - 实现远程 PR 创建、代码托管平台发布或多工作区集中调度。
+- 每个二级任务的完成定义模板：
+  - 修改文件：限定到单一能力闭环内的明确文件集合。
+  - 验证命令：必须可直接在仓库根目录执行。
+  - 完成信号：退出码为 `0`，并出现对应 CLI/测试/产物文件信号。

caigode-0.1.0/.harness/state/codex-progress.md

@@ -0,0 +1,111 @@
+# Codex Progress
+
+## Session Notes
+- Task ID: `TASK-CLI-TEST-001`
+- Status: `done`
+- Changed files: `tests/test_e2e_flow.py`, `tests/fixtures/e2e_workspace/docs/context.txt`, `README.md`, `.harness/state/feature_list.json`, `.harness/state/codex-progress.md`
+- Verification command: `uv run pytest tests/test_e2e_flow.py`
+- Verification result: `passed` (exit code `0`, `1 passed`)
+- Commit hash: `ee7858e`
+- Next step: 当前 `L2 workitem` 已全部完成；如需继续，应先补充新的任务树或做收尾规划
+- Blockers: `(none)`
+
+- Task ID: `TASK-CLI-CHAT-001`
+- Status: `done`
+- Changed files: `src/caigode/interface/repl.py`, `src/caigode/cli.py`, `tests/test_repl_chat.py`, `.harness/state/feature_list.json`, `.harness/state/codex-progress.md`
+- Verification command: `uv run pytest tests/test_repl_chat.py`
+- Verification result: `passed` (exit code `0`, `2 passed`)
+- Commit hash: `b6845f2`
+- Next step: 继续执行下一个已满足依赖且范围清晰的 L2 任务 `TASK-CLI-TEST-001`
+- Blockers: `(none)`
+
+- Task ID: `TASK-CLI-REVIEW-001`
+- Status: `done`
+- Changed files: `src/caigode/cli.py`, `src/caigode/interface/review_handler.py`, `src/caigode/infra/review_artifacts.py`, `tests/test_review_command.py`, `.harness/state/feature_list.json`, `.harness/state/codex-progress.md`
+- Verification command: `uv run pytest tests/test_review_command.py`
+- Verification result: `passed` (exit code `0`, `2 passed`)
+- Commit hash: `f2242c4`
+- Next step: 继续执行下一个已满足依赖且范围清晰的 L2 任务 `TASK-CLI-CHAT-001`
+- Blockers: `(none)`
+
+- Task ID: `TASK-CLI-RUN-001`
+- Status: `done`
+- Changed files: `src/caigode/interface/run_handler.py`, `src/caigode/cli.py`, `tests/test_run_command.py`, `.harness/state/feature_list.json`, `.harness/state/codex-progress.md`
+- Verification command: `uv run pytest tests/test_run_command.py`
+- Verification result: `passed` (exit code `0`, `2 passed`)
+- Commit hash: `0dc2bac`
+- Next step: 继续执行下一个已满足依赖且范围清晰的 L2 任务 `TASK-CLI-REVIEW-001`
+- Blockers: `(none)`
+
+- Task ID: `TASK-CLI-STATUS-001`
+- Status: `done`
+- Changed files: `src/caigode/interface/status_handler.py`, `src/caigode/cli.py`, `tests/test_status_command.py`, `.harness/state/feature_list.json`, `.harness/state/codex-progress.md`
+- Verification command: `uv run pytest tests/test_status_command.py`
+- Verification result: `passed` (exit code `0`, `2 passed`)
+- Commit hash: `e8474a2`
+- Next step: 继续执行下一个已满足依赖且范围清晰的 L2 任务 `TASK-CLI-RUN-001`
+- Blockers: `(none)`
+
+- Task ID: `TASK-CLI-STATE-001`
+- Status: `done`
+- Changed files: `src/caigode/infra/state_store.py`, `tests/test_state_store.py`, `.harness/state/feature_list.json`, `.harness/state/codex-progress.md`
+- Verification command: `uv run pytest tests/test_state_store.py`
+- Verification result: `passed` (exit code `0`)
+- Commit hash: `5d8dfd2`
+- Next step: 继续执行下一个已满足依赖且范围清晰的 L2 任务 `TASK-CLI-CHAT-001`
+- Blockers: `(none)`
+
+- Task ID: `TASK-CLI-AGENT-001`
+- Status: `done`
+- Changed files: `src/caigode/application/agent_service.py`, `src/caigode/domain/task.py`, `tests/test_agent_service.py`, `.harness/state/feature_list.json`, `.harness/state/codex-progress.md`
+- Verification command: `uv run pytest tests/test_agent_service.py`
+- Verification result: `passed` (exit code `0`)
+- Commit hash: `f2855a5`
+- Next step: 继续执行下一个已满足依赖且范围清晰的 L2 任务 `TASK-CLI-STATE-001`
+- Blockers: `(none)`
+
+- Task ID: `TASK-CLI-TOOLS-001`
+- Status: `done`
+- Changed files: `src/caigode/infra/workspace.py`, `src/caigode/infra/shell.py`, `tests/test_workspace_tools.py`, `.harness/state/feature_list.json`, `.harness/state/codex-progress.md`
+- Verification command: `uv run pytest tests/test_workspace_tools.py`
+- Verification result: `passed` (exit code `0`)
+- Commit hash: `4ca6b13`
+- Next step: 继续执行下一个已满足依赖且范围清晰的 L2 任务 `TASK-CLI-AGENT-001`
+- Blockers: `(none)`
+
+- Task ID: `TASK-CLI-OPENAI-001`
+- Status: `done`
+- Changed files: `src/caigode/infra/openai_client.py`, `tests/test_openai_client.py`, `.harness/state/feature_list.json`, `.harness/state/codex-progress.md`
+- Verification command: `uv run pytest tests/test_openai_client.py`
+- Verification result: `passed` (exit code `0`)
+- Commit hash: `f9d6c33`
+- Next step: 继续执行下一个已满足依赖且范围清晰的 L2 任务 `TASK-CLI-TOOLS-001`
+- Blockers: `(none)`
+
+- Task ID: `TASK-CLI-ENTRY-001`
+- Status: `done`
+- Changed files: `.gitignore`, `src/caigode/cli.py`, `tests/test_cli_help.py`, `.harness/state/feature_list.json`, `.harness/state/codex-progress.md`
+- Verification command: `uv run pytest tests/test_cli_help.py`; `uv run python -m caigode.cli --help | grep -q 'chat' && uv run python -m caigode.cli --help | grep -q 'review'`
+- Verification result: `passed` (both commands exit code `0`)
+- Commit hash: `171bd21`
+- Next step: 继续执行下一个已满足依赖的 L2 任务 `TASK-CLI-OPENAI-001`
+- Blockers: `(none)`
+
+- Task ID: `TASK-CLI-CONFIG-001`
+- Status: `done`
+- Changed files: `pyproject.toml`, `uv.lock`, `src/caigode/config.py`, `tests/test_config.py`, `.harness/state/feature_list.json`, `.harness/state/codex-progress.md`
+- Verification command: `uv run pytest tests/test_config.py`
+- Verification result: `passed` (exit code `0`)
+- Commit hash: `c1b56c0`
+- Next step: 继续执行下一个已满足依赖的 L2 任务 `TASK-CLI-ENTRY-001`
+- Blockers: `(none)`
+
+- Task ID: `TASK-CLI-BOOT-001`
+- Status: `done`
+- Changed files: `pyproject.toml`, `uv.lock`, `src/caigode/__init__.py`, `tests/__init__.py`, `.harness/state/feature_list.json`, `.harness/state/codex-progress.md`, `.harness/state/decisions-needed.md`
+- Verification command: `test -f pyproject.toml && test -f uv.lock && test -f src/caigode/__init__.py && test -d tests`
+- Verification result: `passed` (exit code `0`)
+- Commit hash: `9572c5a`
+- Push result: `origin/master` 已更新
+- Next step: 继续执行下一个 L2 任务 `TASK-CLI-CONFIG-001`
+- Blockers: `(none)`

caigode-0.1.0/.harness/state/decisions-needed.md

@@ -0,0 +1,9 @@
+# Decisions Needed
+status: clear
+updated_at: 2026-05-06T23:10:00+08:00
+
+items:
+- (none)
+
+notes:
+- TASK-CLI-BOOT-001 已由人工完成提交并推送（commit: 9572c5a），本次决策门控已关闭。