Skip to content

Commit 8ecc85e

Browse files
loong10kloong10k
committed
feat: 集成可选授权的 CodeReview 插件与 OCR 双模式
1 parent dcbce72 commit 8ecc85e

52 files changed

Lines changed: 3806 additions & 145 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.codex-plugin/plugin.json‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{
2+
"name": "codereview-plugin",
3+
"version": "0.1.0",
4+
"description": "需用户授权的提交语义审查；支持本次、会话自动和会话静默。",
5+
"author": {
6+
"name": "Full Stack Skills / PartMe.AI"
7+
},
8+
"skills": "./skills/",
9+
"interface": {
10+
"displayName": "CodeReview",
11+
"shortDescription": "授权后审查暂存内容，拒绝后会话静默",
12+
"longDescription": "通过 Open Code Review 选择候选文件和规则，默认由当前宿主智能体审查，也可使用 OCR-managed 模式；提供结构化建议，不替代流程验收或静态检查。",
13+
"developerName": "Full Stack Skills / PartMe.AI",
14+
"category": "Productivity",
15+
"capabilities": [],
16+
"defaultPrompt": ["请披露代码外发范围，再询问是否审查本次提交。"]
17+
}
18+
}

‎.github/workflows/test.yml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
name: 离线契约与回归
2+
on:
3+
push:
4+
pull_request:
5+
permissions:
6+
contents: read
7+
jobs:
8+
offline:
9+
strategy:
10+
matrix:
11+
os: [ubuntu-latest, macos-latest]
12+
python: ['3.11', '3.13']
13+
runs-on: ${{ matrix.os }}
14+
steps:
15+
- uses: actions/checkout@v4
16+
- uses: actions/setup-python@v5
17+
with:
18+
python-version: ${{ matrix.python }}
19+
- run: python -m pip install pytest==8.3.4
20+
- run: python -m pytest -q
21+
- run: python scripts/validate_local.py
22+
- run: python -m compileall -q codereview_core scripts hooks
23+
# 不安装 OCR，不配置模型密钥；CI 只做离线验证。

‎.gitignore‎

Lines changed: 13 additions & 143 deletions
Original file line numberDiff line numberDiff line change
@@ -1,143 +1,13 @@
1-
# Logs
2-
logs
3-
*.log
4-
npm-debug.log*
5-
yarn-debug.log*
6-
yarn-error.log*
7-
lerna-debug.log*
8-
9-
# Diagnostic reports (https://nodejs.org/api/report.html)
10-
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
11-
12-
# Runtime data
13-
pids
14-
*.pid
15-
*.seed
16-
*.pid.lock
17-
18-
# Directory for instrumented libs generated by jscoverage/JSCover
19-
lib-cov
20-
21-
# Coverage directory used by tools like istanbul
22-
coverage
23-
*.lcov
24-
25-
# nyc test coverage
26-
.nyc_output
27-
28-
# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
29-
.grunt
30-
31-
# Bower dependency directory (https://bower.io/)
32-
bower_components
33-
34-
# node-waf configuration
35-
.lock-wscript
36-
37-
# Compiled binary addons (https://nodejs.org/api/addons.html)
38-
build/Release
39-
40-
# Dependency directories
41-
node_modules/
42-
jspm_packages/
43-
44-
# Snowpack dependency directory (https://snowpack.dev/)
45-
web_modules/
46-
47-
# TypeScript cache
48-
*.tsbuildinfo
49-
50-
# Optional npm cache directory
51-
.npm
52-
53-
# Optional eslint cache
54-
.eslintcache
55-
56-
# Optional stylelint cache
57-
.stylelintcache
58-
59-
# Optional REPL history
60-
.node_repl_history
61-
62-
# Output of 'npm pack'
63-
*.tgz
64-
65-
# Yarn Integrity file
66-
.yarn-integrity
67-
68-
# dotenv environment variable files
69-
.env
70-
.env.*
71-
!.env.example
72-
73-
# parcel-bundler cache (https://parceljs.org/)
74-
.cache
75-
.parcel-cache
76-
77-
# Next.js build output
78-
.next
79-
out
80-
81-
# Nuxt.js build / generate output
82-
.nuxt
83-
dist
84-
.output
85-
86-
# Gatsby files
87-
.cache/
88-
# Comment in the public line in if your project uses Gatsby and not Next.js
89-
# https://nextjs.org/blog/next-9-1#public-directory-support
90-
# public
91-
92-
# vuepress build output
93-
.vuepress/dist
94-
95-
# vuepress v2.x temp directory
96-
.temp
97-
98-
# Sveltekit cache directory
99-
.svelte-kit/
100-
101-
# vitepress build output
102-
**/.vitepress/dist
103-
104-
# vitepress cache directory
105-
**/.vitepress/cache
106-
107-
# Docusaurus cache and generated files
108-
.docusaurus
109-
110-
# Serverless directories
111-
.serverless/
112-
113-
# FuseBox cache
114-
.fusebox/
115-
116-
# DynamoDB Local files
117-
.dynamodb/
118-
119-
# Firebase cache directory
120-
.firebase/
121-
122-
# TernJS port file
123-
.tern-port
124-
125-
# Stores VSCode versions used for testing VSCode extensions
126-
.vscode-test
127-
128-
# pnpm
129-
.pnpm-store
130-
131-
# yarn v3
132-
.pnp.*
133-
.yarn/*
134-
!.yarn/patches
135-
!.yarn/plugins
136-
!.yarn/releases
137-
!.yarn/sdks
138-
!.yarn/versions
139-
140-
# Vite files
141-
vite.config.js.timestamp-*
142-
vite.config.ts.timestamp-*
143-
.vite/
1+
__pycache__/
2+
*.py[cod]
3+
.pytest_cache/
4+
.venv/
5+
.coverage
6+
htmlcov/
7+
dist/
8+
build/
9+
*.egg-info/
10+
.DS_Store
11+
# OpenSpec 开发工具集成不是分发技能。
12+
.agents/
13+
.claude/

‎.zcode-plugin/plugin.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"name": "codereview-plugin",
3+
"version": "0.1.0",
4+
"description": "用户授权后审查候选提交，支持本次、会话自动与静默。",
5+
"displayName": "CodeReview",
6+
"author": {"name": "Full Stack Skills / PartMe.AI"},
7+
"skills": "./skills/"
8+
}

‎PRIVACY.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# 数据与权限边界
2+
3+
未授权时只读本地 Git 元数据和非敏感作用范围，不启动 OCR 审查。
4+
授权后，默认 Delegation 由 OCR 选择文件/解析规则，当前宿主智能体读取私有候选快照并审查；可选 OCR-managed 可向已披露模型端点发送暂存候选树、基线及必要上下文。两种模式都不保证仅 diff，不要授权处理含敏感信息的仓库。
5+
本插件不安装项目 Git Hooks，不运行项目测试、构建、过滤器或模型建议命令。OCR 不是操作系统沙箱；需信任本机引擎、配置与网络代理，不能承诺隔离恶意进程或任意 HTTP 重定向。
6+
7+
## 状态与保留
8+
9+
- 默认 `$XDG_STATE_HOME/codereview-plugin`，否则用户 `.local/state/codereview-plugin`。`CODEREVIEW_STATE_DIR` 可重定向到仓库外的专用目录。
10+
- 目录权限 0700，会话 JSON/锁文件 0600；按宿主与 session 散列命名，内部按仓库 worktree 分任务。
11+
- 保存授权来源、范围摘要、候选指纹、提交命令、审查报告及用户处置。报告可能包含源码和模型返回的其他敏感内容。默认保留到显式 cleanup，不自动上传证据。
12+
- 不保存 API key，不打印原始引擎 stderr；内存中读取凭据用于校验/脱敏。报告中的当前模型 token 被替换，但不保证识别代码里所有秘密。
13+
- `cleanup` 删除当前会话任务/报告，撤销授权；这是不可恢复的数据清除，不触及其他会话或源码。小型会话偏好和锁文件保留。
14+
- `recover` 将损坏会话 JSON 改名为同目录 `.quarantine-<随机标识>`，可恢复检查但不自动重新授权；隔离副本仍可能有源码，不被 cleanup 隐式删除。
15+
- OCR-managed 使用独立临时 Git 仓库及 0700 结果目录，报告只从 `--output` 文件读取；Delegation 快照在会话状态目录的私有 `runs/` 中保留到宿主回填、撤销或候选变化，然后按受管标记和父目录校验清理。操作系统杀死进程/断电可能留下快照，需确认无运行任务后按明确路径人工清理。
16+
17+
## 接收方解析
18+
19+
Delegation 的接收方固定披露为 `host-agent://<宿主>`，不读取 OCR LLM 配置。OCR-managed 按现有 OCR 文件配置优先于 OCR 环境变量的规则解析；预置 provider、显式 custom provider、legacy llm 与完整 OCR_LLM_* 环境可用，不推测 Anthropic 通用环境或 shell rc 回退。
20+
缺失所需 CLI 能力、无完整接收方、配置开启遥测、自定义 global/project rule、extra_headers/body 返回需处理的错误，不会静默降级到其他模型或执行模式。
21+
环境遥测开关会从子进程移除；配置遥测不会被插件改写。换端点、模型或配置摘要需新授权。
22+
配置核验与引擎读取之间仍有同用户竞态；该 Harness 是合作式权限协议，不是抵抗同用户恶意修改的强安全边界。
23+
24+
## 撤销与卸载
25+
26+
reset/cancel/skip/cleanup 会阻止后续调度并尽力终止正在运行的进程组；已发送给服务商的数据无法撤回，保留策略由对应服务商决定。
27+
卸载宿主插件只停止未来回调；先撤销运行，再按需清理本插件状态。不得通过删除源仓库或其他插件目录来卸载。

‎README.md‎

Lines changed: 86 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,86 @@
1-
# codereview-plugin
2-
codereview-plugin
1+
# CodeReview Plugin
2+
3+
提交前**可选授权**的语义代码审查插件，整合 Open Code Review（OCR）的正式 CLI 接口。
4+
默认先问用户，拒绝后当前会话静默；审查报告是建议，不是强制通过门禁。
5+
6+
状态：`0.1.0` 开发版。已实现本地内核与离线验证；真实模型调用、Codex/ZCode/Kimi 安装加载均 **UNVERIFIED**。远端源码仓库已创建，尚未发布市场。
7+
8+
## 使用体验
9+
10+
第一次准备提交时，智能体披露仓库、执行模式、实际推理方、模型（可知时）和代码范围，并提供：
11+
12+
- **仅本次审查**：同一逻辑提交的失败重试不重复授权；成功提交后结束。
13+
- **当前会话自动审查**：只对同一会话、仓库/worktree、模型与外发策略有效；范围变化重新询问。
14+
- **本会话不再提醒**：不主动审查、不再提醒；仍可手动审查一次，不解除静默。
15+
16+
没有回答不代表同意。审查发现问题后可修复重审、保留风险继续或跳过；不会自动编辑、提交、推送或替其他插件放行。
17+
18+
```mermaid
19+
flowchart LR
20+
A[提交工具调用] --> B{CodeReview 选择}
21+
B -->|未选择| C[暂停：智能体询问用户]
22+
C -->|本次/会话授权| D[隔离暂存快照 → OCR 选文件/解析规则]
23+
B -->|已有授权| D
24+
C -->|不再提醒| E[会话静默]
25+
B -->|静默| E
26+
D --> E1{执行模式}
27+
E1 -->|Delegation 默认| E2[当前宿主智能体审查]
28+
E1 -->|OCR-managed 可选| E3[OCR 调用其配置模型]
29+
E2 --> F[结构化风险与逐文件回执]
30+
E3 --> F
31+
F --> G[用户修复/继续/跳过]
32+
E --> H[本插件不再暂停]
33+
G --> H
34+
H --> I[其他门禁仍独立生效]
35+
```
36+
37+
## 分工
38+
39+
| 插件 | 责任 | 本插件如何协作 |
40+
| --- | --- | --- |
41+
| FlowGuard | SDD 阶段、需求验收、用户豁免、最终裁决 | 只提供 evidence；不推进阶段 |
42+
| CodeGuard | 编译、测试、规范及可执行检查 | 不重复实现这些检查 |
43+
| CodeReview | 提交语义风险、授权、证据绑定 | 不把模型判断当强制通过 |
44+
45+
不要求回调先后顺序。首版交付[证据协议](docs/protocol.md)，不自动修改其他两个插件，也未实现跨插件统一调度。
46+
47+
## 运行要求
48+
49+
- Python 3.11+、POSIX（macOS/Linux）；使用 `fcntl` 和进程组，Windows 原生未支持。WSL 需单独实测。
50+
- Git 2.41+；已安装的 `ocr` 必须支持 `delegate preview/rule --format json`；OCR-managed 还必须支持 `review --output`。按能力探测，不固定单一版本。
51+
- 默认 Delegation：OCR 只选择文件并解析规则，由当前 Codex/ZCode/Kimi 智能体审查，不要求 OCR 配置 LLM。可选 OCR-managed 才要求明确端点、模型与凭据。
52+
- 本机当前 `ocr` 为 v1.6.5，不具备上述正式双模式接口；代码已按上游 v1.12.9 接口适配，但本轮未获授权升级全局工具。`doctor` 仅探测命令能力，不执行 `ocr llm test` 或真实审查。
53+
- 只支持普通暂存区提交、首次提交及显式 `git -C`。`-a`、amend、pathspec、复合命令、冲突/merge/rebase、符号链接、子模块、超限树返回受限状态，可明确跳过。
54+
- 快照限制：基线与候选条目合计 5000、单 blob 4 MiB、去重 blob 总量 64 MiB；不截断后冒充完整审查。
55+
- Hook 不是安全沙箱；Git 别名、动态脚本、宿主未覆盖的工具可能绕过。检查与实际提交间仍存在竞态窗口。
56+
57+
OCR-managed 下，用户配置里的遥测开启、自定义全局/项目规则、额外请求 headers/body 等不能确认外发边界的配置会被拒绝；插件不会擅自修改它们。Delegation 仍需用户授权，因为当前宿主智能体会读取隔离候选快照。详见[隐私](PRIVACY.md)。
58+
59+
## 开发验证
60+
61+
运行时仅 Python 标准库；测试需环境已有 pytest，以下命令不安装依赖、不调用模型：
62+
63+
```bash
64+
python3 -m pytest -q
65+
python3 scripts/validate_local.py
66+
openspec validate consent-based-review --strict
67+
```
68+
69+
CLI：
70+
71+
```bash
72+
python3 scripts/codereview.py --help
73+
python3 scripts/codereview.py prepare --request /absolute/private/request.json
74+
```
75+
76+
请求字段见[CLI 协议](skills/codereview/references/cli.md)。Delegation 的 `review` 只生成计划，宿主完成语义审查后必须调用 `complete-delegated`；OCR-managed 的 `review` 才由 OCR 调用模型。不要把测试夹具成功理解成真实模型成功。
77+
78+
## 安装、维护与验证边界
79+
80+
- [三端安装与卸载](docs/hosts.md)：目前只提供结构及操作说明，本轮未安装。
81+
- [验收证据](docs/verification.md)：规格、测试、未完成项对应关系。
82+
- [OpenSpec 变更](openspec/changes/consent-based-review/proposal.md)：唯一规格事实源，未归档。
83+
- 插件内唯一分发技能 `codereview` 属于 CLI 编排专属技能，声明在 `plugin-local-skills.json`；没有外部受管技能，不创建空壳 `skills.lock.json`。
84+
- `.agents/skills/openspec-*` 是项目开发集成，不纳入分发技能清单。
85+
86+
源码、测试和说明采用 Apache-2.0。上游 OCR 作为用户已有的外部程序调用，不打包其二进制。

‎codereview_core/__init__.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
"""CodeReview 的确定性编排内核。"""

0 commit comments

Comments
 (0)