Skip to content

Commit b06c098

Browse files
ZhuLinsenZhuLinsen
authored
chore: harden ai governance assets (#738)
1 parent a5a0d8e commit b06c098

13 files changed

Lines changed: 768 additions & 127 deletions

File tree

‎.claude/skills/README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Repository Claude Skills
2+
3+
本目录存放仓库级协作 skills，属于版本库资产。
4+
5+
- 规则真源：仓库根目录 `AGENTS.md`
6+
- 兼容入口：根目录 `CLAUDE.md`（应为指向 `AGENTS.md` 的软链接）
7+
- 本目录中的 skill 需要与 `AGENTS.md` 保持一致
8+
- `.claude/reviews/` 属于本地分析产物，不作为规则真源
9+
10+
如果未来需要兼容其他 agent 目录（如 `.agents/skills/` 或 `.github/skills/`），应先明确单一真源，再通过脚本或镜像同步，而不是手工长期维护多份同义内容。

‎.claude/skills/analyze-issue/SKILL.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# Analyze Issue
2+
3+
分析 GitHub Issue，判断其真实性、优先级、仓库责任边界与建议动作。
4+
5+
**Repository**: https://github.com/ZhuLinsen/daily_stock_analysis/issues
6+
7+
## Usage
8+
9+
```text
10+
/analyze-issue <issue_number>
11+
```
12+
13+
## Instructions
14+
15+
分析时使用简洁中文，优先遵循仓库根目录 `AGENTS.md`。
16+
17+
### Step 1: 拉取 Issue 信息
18+
19+
```bash
20+
gh issue view <issue_number> --repo ZhuLinsen/daily_stock_analysis
21+
gh issue view <issue_number> --repo ZhuLinsen/daily_stock_analysis --comments
22+
```
23+
24+
如为 bug，优先核对 issue 模板中是否提供了以下信息：
25+
26+
- 是否已同步到最新版本
27+
- commit hash / 版本基线
28+
- 运行环境与复现步骤
29+
- 日志或报错信息
30+
31+
### Step 2: 回答 4 个核心问题
32+
33+
1. 版本是否明确
34+
2. 问题是否真实且可验证
35+
3. 是否属于仓库责任边界
36+
4. 是否值得立即处理
37+
38+
### Step 3: 结合仓库现状做证据检查
39+
40+
- 阅读相关代码、配置、测试、脚本、工作流与文档
41+
- 如果问题涉及 API、数据源 fallback、报告生成、通知发送、认证、桌面端、发布流程，明确写出影响面
42+
- 判断是实际 bug、环境配置问题、使用方式问题、还是外部依赖问题
43+
- 如怀疑已被修复，检查当前代码而不是只看 issue 描述
44+
45+
### Step 4: 形成结论
46+
47+
至少给出以下字段：
48+
49+
- `版本基线`：最新 / 非最新 / 未提供
50+
- `是否合理`：是/否 + 理由
51+
- `是否是 issue`：是/否 + 理由
52+
- `是否好解决`：是/否 + 难点
53+
- `结论`：`成立 / 部分成立 / 不成立`
54+
- `分类`：`bug / feature / docs / question / external`
55+
- `优先级`：`P0 / P1 / P2 / P3`
56+
- `难度`：`easy / medium / hard`
57+
- `建议动作`：`立即修复 / 排期修复 / 文档澄清 / 关闭`
58+
59+
### Step 5: 生成分析文档
60+
61+
保存到 `.claude/reviews/issues/issue-<number>.md`
62+
63+
## Output Document Format
64+
65+
```markdown
66+
# Issue #<number> Analysis
67+
68+
**Date**: YYYY-MM-DD
69+
**Status**: Pending Review
70+
71+
## Summary
72+
73+
- 版本基线：
74+
- 是否合理：
75+
- 是否是 issue：
76+
- 是否好解决：
77+
- 结论：
78+
- 分类：
79+
- 优先级：
80+
- 难度：
81+
- 建议动作：
82+
83+
## Evidence
84+
85+
- 关键 issue 信息：
86+
- 关键代码/脚本/工作流证据：
87+
88+
## Impact Scope
89+
90+
- 受影响模块：
91+
- 受影响运行路径（本地 / Docker / GitHub Actions / API / Web / Desktop）：
92+
93+
## Root Cause / Main Reasoning
94+
95+
<根因或主要判断依据>
96+
97+
## Proposed Handling
98+
99+
<建议修复、澄清或关闭方式>
100+
101+
## Risks And Rollback
102+
103+
- 风险点：
104+
- 若修复，回滚方式：
105+
106+
## Draft Reply
107+
108+
<建议回复内容>
109+
```
110+
111+
## Allowed Auto-Actions (No Confirmation Needed)
112+
113+
- 拉取 issue 详情与评论
114+
- 阅读相关代码、配置、脚本、工作流和文档
115+
- 生成分析文档
116+
117+
## Actions Requiring Confirmation
118+
119+
执行以下动作前，先询问用户：
120+
121+
1. 添加或修改标签
122+
2. 在 issue 下评论
123+
3. 关闭 issue
124+
4. 开始修复 issue

‎.claude/skills/analyze-pr/SKILL.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# Analyze PR
2+
3+
分析 GitHub Pull Request，评估必要性、描述完整性、验证证据、主要风险与是否可直接合入。
4+
5+
**Repository**: https://github.com/ZhuLinsen/daily_stock_analysis/pulls
6+
7+
## Usage
8+
9+
```text
10+
/analyze-pr <pr_number>
11+
```
12+
13+
## Instructions
14+
15+
分析时使用简洁中文，优先遵循仓库根目录 `AGENTS.md` 和 `.github/PULL_REQUEST_TEMPLATE.md`。
16+
17+
### Step 1: 拉取 PR 基本信息
18+
19+
```bash
20+
gh pr view <pr_number> --repo ZhuLinsen/daily_stock_analysis
21+
gh pr view <pr_number> --repo ZhuLinsen/daily_stock_analysis --comments
22+
gh pr checks <pr_number> --repo ZhuLinsen/daily_stock_analysis
23+
gh pr diff <pr_number> --repo ZhuLinsen/daily_stock_analysis
24+
```
25+
26+
如有失败的 CI，优先查看失败日志，而不是立刻在本地重跑全部检查：
27+
28+
```bash
29+
gh run view <run_id> --log-failed
30+
```
31+
32+
### Step 2: 按仓库模板检查描述完整性
33+
34+
对照 `.github/PULL_REQUEST_TEMPLATE.md`，确认是否覆盖：
35+
36+
- `PR Type`
37+
- `Background And Problem`
38+
- `Scope Of Change`
39+
- `Issue Link`
40+
- `Verification Commands And Results`
41+
- `Compatibility And Risk`
42+
- `Rollback Plan`
43+
44+
### Step 3: 优先使用 CI / Diff 证据
45+
46+
- 先根据 `gh pr checks`、PR diff、现有测试与工作流日志判断问题
47+
- 仅当 CI 未覆盖改动面、CI 结果不足以定性问题、或需要验证关键回归风险时，再补充本地最小验证
48+
- 不要默认切换当前分支或执行 `gh pr checkout`
49+
50+
如果必须补本地验证，按改动面选择最接近的检查，例如：
51+
52+
- 后端：`./scripts/ci_gate.sh` 或 `python -m py_compile <changed_python_files>`
53+
- 前端：`cd apps/dsa-web && npm ci && npm run lint && npm run build`
54+
- 桌面端：先构建 Web，再构建 Electron
55+
56+
### Step 4: 评估正确性与风险
57+
58+
重点检查：
59+
60+
- 是否解决了明确问题，且没有夹带无关改动
61+
- 是否破坏 API / Schema / Web / Desktop 兼容性
62+
- 是否破坏 fallback、降级路径、通知链路或发布流程
63+
- 是否存在明显逻辑错误、异常吞没、安全问题、配置语义变化未同步文档
64+
65+
### Step 5: 生成评审文档
66+
67+
保存到 `.claude/reviews/prs/pr-<number>.md`
68+
69+
## Output Document Format
70+
71+
```markdown
72+
# PR #<number> Analysis
73+
74+
**Date**: YYYY-MM-DD
75+
**Status**: Pending Review
76+
77+
## Findings
78+
79+
- [严重级别] file:line - 问题描述
80+
81+
## Summary
82+
83+
- 必要性：
84+
- 是否有对应 issue：
85+
- PR 类型：
86+
- description 完整性：
87+
- 验证情况：
88+
- 主要风险：
89+
- 是否可直接合入：
90+
91+
## Validation Evidence
92+
93+
- CI 结论：
94+
- 本地补充验证（如有）：
95+
96+
## Compatibility And Risk
97+
98+
- API / Web / Desktop：
99+
- 配置 / Docker / GitHub Actions：
100+
- fallback / 通知 / 报告结构：
101+
102+
## Draft Review Comment
103+
104+
<建议评论内容>
105+
```
106+
107+
## Allowed Auto-Actions (No Confirmation Needed)
108+
109+
- 拉取 PR 元数据、diff、评论和 CI 状态
110+
- 阅读相关代码、模板、工作流与文档
111+
- 在必要时执行最小化本地验证
112+
- 生成评审文档
113+
114+
## Actions Requiring Confirmation
115+
116+
执行以下动作前，先询问用户：
117+
118+
1. 发布评论
119+
2. Approve PR
120+
3. Request changes
121+
4. Merge PR
122+
5. 关闭 PR

‎.claude/skills/fix-issue/SKILL.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# Fix Issue
2+
3+
基于 issue 分析结果实现修复，并按仓库规则补齐验证、风险与回滚说明。
4+
5+
**Repository**: https://github.com/ZhuLinsen/daily_stock_analysis
6+
7+
## Usage
8+
9+
```text
10+
/fix-issue <issue_number>
11+
```
12+
13+
## Prerequisites
14+
15+
优先先完成 `/analyze-issue <issue_number>`，确保问题成立且边界清晰。
16+
17+
## Instructions
18+
19+
### Step 1: 确认分析基线
20+
21+
检查 `.claude/reviews/issues/issue-<number>.md` 是否存在；如果不存在，先补做 issue 分析或在本次修复中补齐最小分析结论。
22+
23+
### Step 2: 选择安全的工作方式
24+
25+
- 默认基于当前工作树做最小相关改动
26+
- 不要默认执行 `git pull`
27+
- 不要默认切换分支或改写用户当前工作状态
28+
- 如果用户明确要求建分支，再执行最小必要的分支操作
29+
30+
### Step 3: 实施修复
31+
32+
- 根据 issue 结论定位相关文件
33+
- 优先复用现有模块、配置入口、脚本和测试
34+
- 保持默认行为向后兼容，避免破坏 fallback / fail-open
35+
- 如果修复涉及用户可见行为、配置语义、CLI/API、部署、通知、报告结构，要同步更新 `README.md`、`docs/CHANGELOG.md`、`.env.example`
36+
37+
### Step 4: 按改动面验证
38+
39+
按 `AGENTS.md` 的验证矩阵执行最接近的检查：
40+
41+
- 后端优先：`./scripts/ci_gate.sh`
42+
- 最低后端要求：`python -m py_compile <changed_python_files>`
43+
- 前端：`cd apps/dsa-web && npm ci && npm run lint && npm run build`
44+
- 桌面端：先构建 Web，再构建桌面端
45+
46+
如无法完成完整验证，必须记录缺口、原因与潜在风险。
47+
48+
### Step 5: 更新 issue 分析文档
49+
50+
在 `.claude/reviews/issues/issue-<number>.md` 中补充：
51+
52+
```markdown
53+
## Fix Implementation
54+
55+
**Date**: YYYY-MM-DD
56+
57+
### Changes Made
58+
59+
- 文件与改动点：
60+
61+
### Validation
62+
63+
- 已执行：
64+
- 未执行：
65+
66+
### Risks
67+
68+
- 风险点：
69+
70+
### Rollback
71+
72+
- 回滚方式：
73+
```
74+
75+
### Step 6: 需要确认的后续动作
76+
77+
只有在用户明确确认后，才执行：
78+
79+
- 建分支
80+
- `git commit`
81+
- `git push`
82+
- 创建 PR
83+
- 在 issue 下回复或关闭 issue
84+
85+
## Allowed Auto-Actions (No Confirmation Needed)
86+
87+
- 阅读和分析代码
88+
- 应用与当前任务直接相关的最小修复
89+
- 运行非破坏性的本地验证
90+
- 更新本地 issue 分析文档
91+
92+
## Actions Requiring Confirmation
93+
94+
1. 切换或创建分支
95+
2. `git commit`
96+
3. `git push`
97+
4. 创建 PR
98+
5. 回复或关闭 issue

‎.github/copilot-instructions.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Repository Instructions
2+
3+
Canonical source: [`AGENTS.md`](../AGENTS.md).
4+
5+
If any instruction in this file conflicts with `AGENTS.md`, follow `AGENTS.md`.
6+
7+
## Core Rules
8+
9+
- Respect directory boundaries:
10+
- Backend: `src/`, `data_provider/`, `api/`, `bot/`
11+
- Web: `apps/dsa-web/`
12+
- Desktop: `apps/dsa-desktop/`
13+
- Deployment/workflows: `scripts/`, `.github/workflows/`, `docker/`
14+
- Do not run `git commit`, `git tag`, or `git push` without explicit user confirmation.
15+
- Do not hardcode secrets, accounts, ports, model names, absolute environment-specific paths, or environment-specific branches.
16+
- Reuse existing modules, configuration entrypoints, scripts, and tests instead of adding parallel implementations.
17+
- For user-visible behavior changes, CLI/API changes, deployment changes, notification changes, or report-structure changes, update `README.md` and `docs/CHANGELOG.md`.
18+
- When config semantics change, sync `.env.example` and assess impact on local runs, Docker, GitHub Actions, API, Web, and Desktop.
19+
20+
## Validation
21+
22+
- Backend changes: prefer `./scripts/ci_gate.sh`; at minimum run `python -m py_compile` on changed Python files and the closest deterministic tests.
23+
- Web changes: run `cd apps/dsa-web && npm ci && npm run lint && npm run build`.
24+
- Desktop changes: build web first, then desktop if feasible.
25+
- Review work should prioritize CI evidence (`gh pr checks`, workflow logs) before re-running local validation.
26+
- AI governance changes: run `python scripts/check_ai_assets.py`.
27+
28+
## AI Asset Governance
29+
30+
- `AGENTS.md` is the single source of truth for repository AI collaboration rules.
31+
- `CLAUDE.md` must remain a symlink to `AGENTS.md`.
32+
- Use `.github/instructions/*.instructions.md` for path-specific guidance.
33+
- Current repository collaboration skills live in `.claude/skills/`; keep them aligned with `AGENTS.md`.

0 commit comments

Comments
 (0)