Skip to content

Commit 509ca6d

Browse files
sou350121sou350121
authored
Merge pull request #1 from sou350121/imh-task-001-scenario-sandbox
IMH-TASK-001: policy scenario sandbox (load + validate + approx)
2 parents 1940f90 + f245cfb commit 509ca6d

157 files changed

Lines changed: 21368 additions & 4763 deletions

File tree

Some content is hidden

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

‎.editorconfig‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,4 +35,11 @@ indent_size = 2
3535

3636

3737

38+
39+
40+
41+
42+
43+
44+
3845

‎.gitattributes‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,4 +34,11 @@
3434

3535

3636

37+
38+
39+
40+
41+
42+
43+
3744

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: 文档与协作流程（多 Agent 闭环）
4+
url: https://github.com/sou350121/investment-masters-handbook/blob/main/docs/MULTI_AGENT_WORKFLOW.md
5+
about: Requirement -> Issue -> PR -> Review -> Fix -> Merge 的协作说明（最小必要上下文）
6+
7+
8+

‎.github/ISSUE_TEMPLATE/imh_task.yml‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
name: IMH Task（Spec -> PR -> Review）
2+
description: Requirement Agent 用于产出“最小必要上下文”的可执行 Issue（便于 Coder/Reviewer 闭环协作）
3+
title: "[IMH] <简短标题>"
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
### 说明
9+
- **Coder Agent**：只实现本 Issue 定义的范围（禁止“顺手重构”）。
10+
- **Reviewer Agent**：Review 意见必须 **inline comment** 或附带 **文件路径:行号** 精确定位。
11+
- **最小必要上下文**：不要要求 Coder/Reviewer 去“猜你想要什么”；把验收标准、边界、依赖写清楚。
12+
13+
- type: input
14+
id: task_id
15+
attributes:
16+
label: Task ID（可选）
17+
description: 如果你在 docs/tasks 里有编号，可填写如 IMH-TASK-001
18+
placeholder: IMH-TASK-001
19+
validations:
20+
required: false
21+
22+
- type: textarea
23+
id: goal
24+
attributes:
25+
label: 目标（Goal）
26+
description: 一句话 + 1-3 条补充，明确“要解决什么问题”
27+
placeholder: |
28+
在 IMH 系统中引入 XXX 能力，解决 YYY 痛点，并能通过 ZZZ 方式验证。
29+
validations:
30+
required: true
31+
32+
- type: textarea
33+
id: scope
34+
attributes:
35+
label: 范围（Scope）
36+
description: 明确 In-scope / Out-of-scope（Reviewer 以此做 Scope Check）
37+
value: |
38+
**In-scope**
39+
-
40+
41+
**Out-of-scope**
42+
-
43+
validations:
44+
required: true
45+
46+
- type: textarea
47+
id: spec
48+
attributes:
49+
label: 详细规格（Spec）
50+
description: 建议按“数据/后端 API/前端 UI/兼容性/错误处理/日志溯源”分段写
51+
placeholder: |
52+
### A. 数据/配置
53+
- 文件：path/to/file
54+
- 结构示例：...
55+
56+
### B. 后端 API
57+
- GET /xxx：...
58+
- POST /yyy：...
59+
60+
### C. 前端 UI
61+
- 组件：...
62+
- 交互：...
63+
validations:
64+
required: true
65+
66+
- type: textarea
67+
id: acceptance
68+
attributes:
69+
label: 验收标准（DoD）
70+
description: 使用 checklist，写可验证的结果（而不是“实现某某功能”）
71+
value: |
72+
- [ ]
73+
- [ ]
74+
- [ ]
75+
validations:
76+
required: true
77+
78+
- type: textarea
79+
id: constraints
80+
attributes:
81+
label: 限制与不变量（Constraints）
82+
description: 明确不能改什么、必须保持什么行为/风格/兼容性
83+
placeholder: |
84+
- 不要修改 RAG 核心逻辑
85+
- 保持前端 Material UI 风格一致
86+
- 不引入新依赖（除非明确批准）
87+
validations:
88+
required: false
89+
90+
- type: textarea
91+
id: dependencies
92+
attributes:
93+
label: 依赖关系（Dependencies）
94+
description: 需要先完成的 Issue/PR、外部资源、配置等
95+
placeholder: |
96+
- Depends on: #123
97+
- Blocks: #456
98+
validations:
99+
required: false
100+
101+
- type: textarea
102+
id: test_plan
103+
attributes:
104+
label: 运行/验证方式（Test Plan / Runbook）
105+
description: Coder 应在 PR 里复述并给出实际运行命令与结果
106+
placeholder: |
107+
- 运行：python scripts/xxx.py
108+
- 手动验证：打开 web 页面，点击...
109+
- 预期输出：...
110+
validations:
111+
required: false
112+
113+
- type: textarea
114+
id: notes
115+
attributes:
116+
label: 参考资料/链接（可选）
117+
description: 相关文档、代码入口、截图等（避免要求对方自己搜）
118+
placeholder: |
119+
- docs/xxx.md
120+
- 相关代码：path/to/file
121+
validations:
122+
required: false
123+
124+

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
## 关联 Issue
2+
3+
- Closes #
4+
5+
## 变更摘要
6+
7+
-
8+
9+
## 范围声明（Scope）
10+
11+
**In-scope**
12+
-
13+
14+
**Out-of-scope**
15+
-
16+
17+
## 运行与验证（How to test）
18+
19+
> 贴出你实际运行过的命令与结果（不要只写“已测试”）。
20+
21+
- **后端/脚本**：
22+
- `python scripts/check_links.py`
23+
- `python scripts/validate_front_matter.py`
24+
- `python scripts/check_router_config.py`
25+
- `python scripts/scan_sensitive.py`
26+
- `python scripts/generate_artifacts.py && git status --porcelain`
27+
- **Web（如涉及）**：
28+
- `cd web && npm install && npm run dev`
29+
- 手动步骤：
30+
-
31+
- 预期结果：
32+
-
33+
34+
## 风险 & 回滚
35+
36+
- **风险点**：
37+
-
38+
- **回滚方式**：
39+
- `git revert <commit>`
40+
41+
## Reviewer 指引（便于定位）
42+
43+
> Reviewer 要求：优先使用 GitHub inline comment；若无法 inline，必须提供 **文件路径:行号**。
44+
45+
- **关键改动点**：
46+
- `path/to/file:line` - 说明
47+
48+
## Checklist
49+
50+
- [ ] 只实现 Issue 定义的范围（无额外扩展/无无关重构）
51+
- [ ] 不触碰 Issue 约束中明确禁止的模块/文件
52+
- [ ] CI 通过（或说明失败原因与修复计划）
53+
- [ ] 生成文件已同步（如涉及）且 `git status` 干净
54+
- [ ] PR 描述包含可复现的验证步骤
55+
56+
57+
58+

‎.github/REVIEW_GUIDE.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Review Guide（Reviewer Agent）
2+
3+
> 目标：建立“可定位、可执行”的 Review 闭环，减少来回沟通成本。
4+
5+
## 基本原则
6+
7+
- **需求对齐优先**：先对照 Issue 的 Goal/Scope/DoD，确认是否“少做/多做/跑偏”。
8+
- **最小必要建议**：优先给出能 unblock 合并的修改；“可选优化”单独标注，不阻塞。
9+
- **必须可定位**：优先使用 GitHub inline comment；若无法 inline，必须提供 **文件路径:行号**。
10+
11+
## 评论格式（建议）
12+
13+
请按严重级别标注，方便 Coder 排优先级：
14+
15+
- **[blocker]**：不修不能合（错误逻辑/安全/数据损坏/测试缺失导致不可验证）
16+
- **[major]**：建议修复后合（易错/可维护性差/边界情况缺失）
17+
- **[minor]**：小问题（命名/注释/一致性）
18+
- **[nit]**：非阻塞（格式/语气）
19+
20+
每条评论至少包含：
21+
22+
- **定位**：GitHub inline comment 或 `path/to/file:line`（可用 `Lx-Ly`）
23+
- **问题**：现状是什么
24+
- **影响**：为什么重要（关联 DoD / 约束 / 潜在 bug）
25+
- **建议**：给出明确修复方向（必要时贴伪代码/示例）
26+
27+
## 示例
28+
29+
- **[blocker] `services/rag_service.py:L45-L60`**：`/api/policy/scenarios` 读取 YAML 缺少异常处理（文件不存在/格式错误会 500）。
30+
- **影响**：DoD 要求接口稳定可用；前端加载会直接失败。
31+
- **建议**：捕获 `FileNotFoundError`/`yaml.YAMLError`，返回结构化错误（HTTP 400/500 区分）。
32+
33+
## Scope Check（强制）
34+
35+
- 若发现“超出 Issue 范围”的改动：必须指出具体文件/提交点，并要求移除或拆分到新 Issue。
36+
37+
38+
39+

‎.github/workflows/quality.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,10 @@ jobs:
3737
run: |
3838
python scripts/scan_sensitive.py
3939
40+
- name: Validate task docs (minimal context)
41+
run: |
42+
python scripts/validate_tasks.py
43+
4044
- name: Generate artifacts and ensure repo is clean
4145
run: |
4246
python scripts/generate_artifacts.py

‎.gitignore‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,5 +11,33 @@ venv/
1111
.env
1212
.DS_Store
1313

14+
# Cursor / IDE
15+
.cursor/
16+
17+
# Python tooling
18+
.pytest_cache/
19+
20+
# Node / Next
21+
node_modules/
22+
web/node_modules/
23+
web/.next/
24+
25+
# Local artifacts / runtime data
26+
vectorstore/
27+
logs/
28+
29+
# Temp files created during debugging
30+
_tmp_*.py
31+
_tmp_*.json
32+
33+
# Local backtest scratch (generated)
34+
data_news_*.csv
35+
data_signals_*.csv
36+
_gen_*.py
37+
_run_*.py
38+
results_sim*/
39+
results_sim_long*/
40+
results_test/
41+
1442

1543

‎AGENT.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,15 @@ investment-masters-handbook/
5454
## 常用命令
5555

5656
```bash
57+
# （推荐）启动后端（同时托管 Web 静态站点）
58+
python -m pip install -r requirements.txt
59+
python services/rag_service.py
60+
61+
# 构建 Web 静态站点（生成 web/out，由后端托管）
62+
cd web
63+
npm install
64+
npm run build
65+
5766
# 规则查询
5867
python tools/rule_query.py --scenario "市场恐慌"
5968
python tools/rule_query.py --investor buffett
@@ -68,6 +77,27 @@ python scripts/validate_front_matter.py
6877
python scripts/check_router_config.py
6978
```
7079

80+
## Web UI / Policy Gate 场景沙盒（Scenario Sandbox）
81+
82+
### 打开网页
83+
84+
1. 构建前端静态站点：
85+
- `cd web && npm install && npm run build`
86+
2. 启动后端：
87+
- `python services/rag_service.py`
88+
3. 打开浏览器：
89+
- `http://localhost:8001/imh/`（推荐）
90+
91+
> 快速自检：`GET /health` 应返回 `{"status":"ok","vectorstore_ready": ...}`。
92+
> 如果你看到的是 `{"status":"healthy"}` 或 `/api/policy/*` 返回 404，说明你启动的是其它项目的后端（端口冲突）。
93+
94+
### 验证场景沙盒
95+
96+
- 进入 Web UI → 展开 **Policy Gate** 面板 → 在 **🚀 场景沙盒** 点击场景
97+
- 点击 **生成 Policy Gate 护栏**，页面会展示 ✅/❌ 校验报告
98+
- 场景来源：`config/scenarios.yaml`
99+
- Policy Gate 规则来源：`config/policy_gate.yaml`
100+
71101
## 代码规范
72102

73103
- **Markdown**: 使用中文，IF-THEN-BECAUSE 格式写决策规则

0 commit comments

Comments
 (0)