# Obsidian Project Logic Docs

> Use when the user asks to summarize field value sources, calculation rules, business logic, API/interface logic, code behavior, or implementation口径 and write/update them in Obsidian project notes. Trigger on requests like “总结字段取值方式写到 Obsidian”, “把业务逻辑补到个人功能开发说明”, “更新接口逻辑到项目资料”, or “把计算口径沉淀到笔记”; always locate the matching project, note name, and section, source-verify from code/API/config/logs, draft in the note’s existing format, and get explicit user confirmation before writing.

- Skill: `xfcycc/obsidian-project-logic-docs` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add xfcycc/obsidian-project-logic-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xfcycc/obsidian-project-logic-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: xfcycc (https://skillmd.com/u/xfcycc)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/xfcycc/obsidian-project-logic-docs

---


# Obsidian Project Logic Docs

用于把代码中真实存在的字段取值方式、计算逻辑、业务规则、接口逻辑，整理进本地 Obsidian 项目资料。默认中文。

## 硬约束

- 先找项目、笔记名、章节；找不到就继续查，不要把内容写进相似但不确定的文件。
- 写入 Obsidian 前必须二次确认，即使用户说“更新到 Obsidian”也先预览。
- 不凭记忆写口径；必须回到代码、接口、配置、SQL、日志、提交 diff 或现有正式文档核对。
- 只改用户要求的目标笔记和目标章节，不顺手整理其他笔记。
- Obsidian 正文保持干净，不写内部推理、工具输出、memory citation、“我检查了...”这类过程说明。
- 用户只要总结时，只输出总结；用户要求写入时，先给确认预览，收到明确确认后再落盘。

## 工作流

### 1. 定位项目和笔记

先确认当前工作区和真实子仓：

```bash
pwd
find . -maxdepth 2 -name .git -type d -prune
```

再定位 Obsidian 项目资料。优先顺序：

1. 用户点名的项目、笔记名、章节。
2. 当前工作区或 memory 中已知的项目资料目录。
3. 本地 vault 常见目录：

```text
/Users/caiguoyu/Library/Mobile Documents/iCloud~md~obsidian/Documents/cainiao/项目资料
```

常用查找：

```bash
rg -n "<项目名>|<模块名>|<笔记名>|<章节关键词>" "<项目资料目录>"
find "<项目资料目录>" -maxdepth 8 -type f -name "*<关键词>*.md"
```

确认目标时至少锁定：

- 项目目录，例如 `项目资料/盛迭/节能管理`。
- 目标笔记绝对路径，例如 `.../节能管理-个人功能开发说明.md`。
- 目标章节标题，例如 `## 1.大家乐大屏字段` 或 `### 当前实现口径`。

### 2. 回到事实源核对

按任务类型读事实源：

- 字段取值方式：读前端展示字段、接口模型、VO/DTO、Mapper SQL、service 组装逻辑。
- 计算逻辑：读计算入口、私有计算方法、SQL 聚合、常量、阈值、空值/负数/无数据处理。
- 业务逻辑：读 controller/service/manager 流程、状态枚举、表字段、现有项目说明。
- 接口逻辑：读 controller 路径、前端 API 调用、请求/响应模型、拆分接口、刷新方式。
- 运行态问题：读配置、日志、实际请求结果；不要只看源码推断。

记录口径时要保留这些要素：

- 数据来源：表、字段、接口、配置项、常量。
- 时间范围：今日、昨日同一时段、本月、最近 N 天、当前时刻。
- 计算公式：用可读公式写清楚分子、分母、边界。
- 过滤条件：删除标记、状态、有效门店、有效基线、设备类型、阈值。
- 边界处理：空值、0、负数、无数据、样本不足、兜底值。
- 前后端关系：接口是否拆分，前端是否二次过滤、格式化、合并多个接口。

### 3. 对齐目标笔记格式

先读目标文件上下文，不要新造风格：

```bash
sed -n '1,180p' "<目标笔记>"
```

如果目标已有字段表，优先沿用它的列。常见列：

```text
模块 | 字段名 | 类型 | 关联表/字段 | 说明 | 示例 | 单位 | 备注
```

如果需要补充长口径，优先新增或更新一个小节，常用结构：

```markdown
### 当前实现口径

接口入口：

- ...

时间口径：

- ...

字段取值与计算：

- ...

状态、告警与边界：

- ...
```

写法要求：

- 用业务可读语言，不只贴类名或方法名。
- 公式写全，例如 `今日节能量 = max(日基线 - 今日实际用电, 0)`。
- 表格中旧口径要直接替换，不在旁边追加矛盾说明。
- 对“暂定”“待定”“旧接口”等过时描述，要改成当前已核实口径。

### 4. 写入前二次确认

在动文件前，先发给用户确认预览。必须包含：

- 目标文件绝对路径。
- 目标章节或插入位置。
- 本次会新增/替换的内容摘要。
- 一段可读预览，足够判断格式和内容。
- 事实源摘要，例如“已对照 service、Mapper XML、前端 API 调用”。

确认话术保持简短：

```text
我准备写入：
目标文件：...
目标章节：...
改动摘要：...

预览：
...

你确认后我再写入。
```

只有用户明确回复“确认”“可以”“写入”“更新吧”“ok”等，才编辑文件。

### 5. 写入和验证

确认后使用 `apply_patch` 做最小修改。不要用 shell 重写整篇笔记。

写完后回读目标区域：

```bash
sed -n '<start>,<end>p' "<目标笔记>"
rg -n "<关键公式>|<关键字段>|<章节标题>" "<目标笔记>"
```

最终回复说明：

- 已写入的目标文件。
- 写入/更新了哪些口径。
- 验证方式。
- 如果有代码仓未提交脏改，说明没有触碰它们。

## 适配示例

用户说：“将现在的大屏字段计算逻辑更新到 Obsidian 里的个人功能开发说明里。”

执行要点：

1. 在代码中核对大屏 controller、service、Mapper、前端 API。
2. 在项目资料中找到对应项目的 `个人功能开发说明.md`。
3. 识别已有字段表和“重点关注字段”格式。
4. 草拟“当前实现口径”和表格更新。
5. 先预览目标路径、章节、改动摘要，等确认后写入。

用户说：“把这个接口字段的取值方式补到项目资料。”

执行要点：

1. 先从接口入口追到返回字段的真实赋值点。
2. 核对字段名、类型、来源表、枚举、过滤条件和空值处理。
3. 找到项目资料里对应功能说明或接口说明章节。
4. 预览补写内容，确认后写入。