chore(skill): 清理全部 23 条历史校验警告
- 11 个超 20KB 的 SKILL.md 拆分，大章节移入 references/details.md - 7 处非标准字段（arguments/user_invocable）移入 metadata - 修 req-dev 4 条相对链接；validate 跳过行内代码避免  误报 - validate-skills.py: 23 warns -> 0 warns，0 errors
This commit is contained in:
johnQ
@@ -5,9 +5,6 @@ metadata:
|
||||
invocation: user-invoked
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# 思源笔记 API 集成 Skill
|
||||
|
||||
## 环境变量配置（必须）
|
||||
|
||||
本 skill 通过环境变量读取思源笔记连接信息，不同用户/组织配置不同的值。
|
||||
@@ -520,127 +517,6 @@ markdown = f"""# {today} 工作日志
|
||||
|
||||
## 会议记录
|
||||
|
||||
## 备注
|
||||
"""
|
||||
|
||||
# 获取或创建日记笔记本
|
||||
notebooks = api.list_notebooks()
|
||||
diary_nb = next((nb for nb in notebooks if nb["name"] == "日记"), None)
|
||||
if not diary_nb:
|
||||
diary_nb = api.create_notebook("日记")["notebook"]
|
||||
|
||||
# 使用 upsert_doc 避免重复创建
|
||||
doc_id = api.upsert_doc(diary_nb["id"], f"/{today}", markdown)
|
||||
print(f"每日笔记: {doc_id}")
|
||||
```
|
||||
|
||||
### 场景 2: 批量导入 Markdown 文件
|
||||
|
||||
```python
|
||||
from pathlib import Path
|
||||
|
||||
api = SiYuanAPI()
|
||||
notebook_id = "目标笔记本ID"
|
||||
md_folder = "/path/to/markdown/files"
|
||||
|
||||
for md_file in Path(md_folder).glob("*.md"):
|
||||
with open(md_file, "r", encoding="utf-8") as f:
|
||||
content = f.read()
|
||||
|
||||
doc_name = md_file.stem
|
||||
# 使用 upsert_doc 支持增量导入，避免重复
|
||||
doc_id = api.upsert_doc(notebook_id, f"/{doc_name}", content)
|
||||
print(f"导入: {doc_name} -> {doc_id}")
|
||||
```
|
||||
|
||||
### 场景 3: 搜索并汇总
|
||||
|
||||
```python
|
||||
api = SiYuanAPI()
|
||||
|
||||
# 搜索所有包含"会议"的内容
|
||||
results = api.search("会议")
|
||||
blocks = results.get("blocks", [])
|
||||
|
||||
print(f"找到 {len(blocks)} 条相关内容:")
|
||||
for block in blocks[:10]:
|
||||
print(f"- {block.get('content', '')[:50]}...")
|
||||
```
|
||||
|
||||
### 场景 4: 发布合同到飞书云文档
|
||||
|
||||
```python
|
||||
from siyuan import SiYuanAPI
|
||||
|
||||
api = SiYuanAPI()
|
||||
|
||||
# 1. 从思源笔记导出合同内容
|
||||
contract_doc_id = "20260202080355-2c0vgac" # 合同文档 ID
|
||||
markdown_content = api.export_md(contract_doc_id)
|
||||
|
||||
# 2. 使用飞书 MCP 创建云文档
|
||||
# 调用 feishu-doc MCP 的 create_and_write_document 工具
|
||||
# - title: "物流服务合同-妗晨与名风"
|
||||
# - content: markdown_content
|
||||
# - folder_token: (可选，指定目标文件夹)
|
||||
|
||||
# 3. 完整的发布函数
|
||||
def publish_to_feishu(doc_id: str, doc_title: str = None) -> dict:
|
||||
"""
|
||||
将思源笔记文档发布到飞书云文档
|
||||
|
||||
Args:
|
||||
doc_id: 思源笔记文档 ID
|
||||
doc_title: 飞书文档标题（可选，默认使用原文档标题）
|
||||
|
||||
Returns:
|
||||
dict: {"siyuan_doc_id": str, "content": str, "feishu_url": str}
|
||||
"""
|
||||
api = SiYuanAPI()
|
||||
|
||||
# 导出 Markdown 内容
|
||||
content = api.export_md(doc_id)
|
||||
|
||||
# 获取原文档标题（如果未指定）
|
||||
if not doc_title:
|
||||
doc_info = api.get_block(doc_id)
|
||||
doc_title = doc_info.get("content", "未命名文档")
|
||||
|
||||
# 返回准备好的内容，由调用者使用 feishu-doc MCP 创建
|
||||
return {
|
||||
"siyuan_doc_id": doc_id,
|
||||
"doc_title": doc_title,
|
||||
"content": content
|
||||
}
|
||||
|
||||
# 使用示例
|
||||
result = publish_to_feishu("20260202080355-2c0vgac", "物流服务合同-妗晨与名风-2026")
|
||||
print(f"准备发布: {result['doc_title']}")
|
||||
print(f"内容长度: {len(result['content'])} 字符")
|
||||
|
||||
# 然后调用 feishu-doc MCP:
|
||||
# mcp__feishu-doc__create_and_write_document(
|
||||
# title=result["doc_title"],
|
||||
# content=result["content"]
|
||||
# )
|
||||
```
|
||||
|
||||
**工作流说明**:
|
||||
|
||||
1. **创建合同** (biz-contract 技能) → 生成合同 Markdown 文本
|
||||
2. **存储到思源** (siyuan 技能) → 保存到"商务合同"笔记本，便于预览和修改
|
||||
3. **发布到飞书** (feishu-doc MCP) → 导出并创建飞书云文档
|
||||
|
||||
**商务合同笔记本配置**:
|
||||
|
||||
| 配置项 | 值 |
|
||||
|--------|-----|
|
||||
| 笔记本名称 | 商务合同 |
|
||||
| 笔记本 ID | `20260202080313-kjtgg1j` |
|
||||
| 路径规范 | `/{合同类型}/{甲方简称}-{乙方简称}-{年份}` |
|
||||
|
||||
---
|
||||
|
||||
## 注意事项
|
||||
|
||||
- API Token 需要保密，不要提交到代码仓库
|
||||
@@ -668,72 +544,6 @@ print(f"内容长度: {len(result['content'])} 字符")
|
||||
- **最后更新**: 2026-01-15 07:35:00 ACDT
|
||||
- **验证时间**: 2026-01-15 08:00:00 CST
|
||||
|
||||
## 配置变更
|
||||
|
||||
**变更时间**: 2026-01-15 01:12:00 CST
|
||||
**生效时间**: 2026-01-15 01:15:00 CST
|
||||
```
|
||||
|
||||
#### ❌ 错误示例
|
||||
|
||||
```markdown
|
||||
- **发生时间**: 2026-01-15
|
||||
- **创建时间**: 2026-01-15
|
||||
- **最后更新**: 今天
|
||||
- **验证时间**: 早上
|
||||
```
|
||||
|
||||
#### 时间格式规范
|
||||
|
||||
| 场景 | 格式 | 示例 |
|
||||
|------|------|------|
|
||||
| 精确时间点 | `YYYY-MM-DD HH:MM:SS TZ` | `2026-01-15 02:00:01 CST` |
|
||||
| 时间范围 | `YYYY-MM-DD HH:MM:SS - HH:MM:SS TZ` | `2026-01-15 00:00:00 - 00:46:00 CST` |
|
||||
| 跨天时间范围 | `YYYY-MM-DD HH:MM:SS - YYYY-MM-DD HH:MM:SS TZ` | `2026-01-15 23:00:00 - 2026-01-16 01:00:00 CST` |
|
||||
|
||||
**时区标注**:
|
||||
- CST: 中国标准时间 (服务器时间、生产环境)
|
||||
- ACDT: 澳大利亚中部夏令时 (au-dev 本地开发时间)
|
||||
- UTC: 协调世界时 (国际标准)
|
||||
|
||||
### 文档元信息要求
|
||||
|
||||
所有运维、技术类笔记文档必须在开头包含元信息：
|
||||
|
||||
```markdown
|
||||
# 文档标题
|
||||
|
||||
**创建时间**: YYYY-MM-DD HH:MM:SS TZ
|
||||
**创建人**: qiudl / Claude
|
||||
**最后更新**: YYYY-MM-DD HH:MM:SS TZ
|
||||
**文档状态**: ✅ 已完成 / 🔄 进行中 / ⚠️ 待验证 / ❌ 已废弃
|
||||
**相关项目**: 项目名称
|
||||
**标签**: #运维 #数据库 #备份
|
||||
|
||||
---
|
||||
|
||||
[正文内容...]
|
||||
```
|
||||
|
||||
### 事件记录规范
|
||||
|
||||
记录重大事件或故障时必须包含：
|
||||
|
||||
1. **事件时间**: 完整的开始和结束时间（精确到秒）
|
||||
2. **严重程度**: P0/P1/P2/P3
|
||||
3. **影响范围**: 具体说明受影响的系统和用户
|
||||
4. **事件描述**: 清晰简洁的事件说明
|
||||
5. **恢复过程**: 详细的恢复步骤和时间点
|
||||
6. **恢复完成时间**: 精确的恢复完成时间
|
||||
7. **根本原因**: RCA (Root Cause Analysis)
|
||||
8. **预防措施**: 包含完成时间的预防措施
|
||||
9. **相关文档**: 链接到相关技术文档或代码仓库
|
||||
|
||||
**模板**:
|
||||
|
||||
```markdown
|
||||
# YYYY-MM-DD 事件标题
|
||||
|
||||
## 事件概述
|
||||
|
||||
- **发生时间**: YYYY-MM-DD HH:MM:SS - HH:MM:SS TZ
|
||||
@@ -893,83 +703,11 @@ YYYY-MM-DD HH:MM:SS - 验证通过
|
||||
记录手动运维操作时应包含：
|
||||
|
||||
```markdown
|
||||
## YYYY-MM-DD HH:MM 操作记录
|
||||
|
||||
**操作时间**: YYYY-MM-DD HH:MM:SS TZ
|
||||
**操作人**: qiudl / Claude
|
||||
**操作类型**: 数据库操作 / 服务重启 / 配置变更 / 部署发布
|
||||
**操作内容**: 简短描述
|
||||
## 详细内容
|
||||
|
||||
### 详细步骤
|
||||
以下章节已移到 [references/details.md](references/details.md)：
|
||||
|
||||
1. **步骤 1** (HH:MM:SS)
|
||||
```bash
|
||||
具体命令
|
||||
```
|
||||
结果: [...]
|
||||
|
||||
2. **步骤 2** (HH:MM:SS)
|
||||
```bash
|
||||
具体命令
|
||||
```
|
||||
结果: [...]
|
||||
|
||||
### 验证结果
|
||||
|
||||
**验证时间**: YYYY-MM-DD HH:MM:SS TZ
|
||||
**验证结果**: ✅ 成功 / ❌ 失败 / ⚠️ 部分成功
|
||||
|
||||
[验证详情...]
|
||||
|
||||
### 回滚方案
|
||||
|
||||
如需回滚，执行以下步骤：
|
||||
```bash
|
||||
回滚命令
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**记录时间**: YYYY-MM-DD HH:MM:SS TZ
|
||||
```
|
||||
|
||||
### 检查清单
|
||||
|
||||
在创建或更新思源笔记文档时，请检查：
|
||||
|
||||
- [ ] 所有时间记录都包含完整时间戳（精确到秒）
|
||||
- [ ] 所有时间戳都标注了时区（CST/ACDT/UTC）
|
||||
- [ ] 文档包含元信息（创建时间、创建人、状态）
|
||||
- [ ] 事件记录包含完整的时间范围和时间线
|
||||
- [ ] 技术方案包含各阶段的时间规划
|
||||
- [ ] 会议记录包含会议时间和记录完成时间
|
||||
- [ ] 操作日志包含操作时间、验证时间
|
||||
- [ ] 所有时间使用 24 小时制
|
||||
- [ ] 时间格式一致（YYYY-MM-DD HH:MM:SS TZ）
|
||||
- [ ] 跨天操作明确标注日期变化
|
||||
|
||||
### 为什么需要完整时间戳
|
||||
|
||||
1. **故障排查**: 精确时间有助于关联服务器日志和追踪问题根源
|
||||
2. **时间顺序**: 明确事件的先后关系，构建完整的时间线
|
||||
3. **性能分析**: 精确计算操作耗时，识别性能瓶颈
|
||||
4. **审计追踪**: 完整的操作记录，满足合规要求
|
||||
5. **跨时区协作**: 明确时区避免混淆（澳洲团队 vs 中国服务器）
|
||||
6. **自动化集成**: 便于后续工具提取时间信息进行分析
|
||||
7. **知识沉淀**: 便于后续查阅和学习，理解决策的时间背景
|
||||
|
||||
### 常见错误和修正
|
||||
|
||||
| 错误写法 | 正确写法 | 说明 |
|
||||
|---------|---------|------|
|
||||
| 今天下午 | 2026-01-15 14:30:00 CST | 避免模糊表述 |
|
||||
| 凌晨 | 2026-01-15 02:00:00 CST | 明确具体时间 |
|
||||
| 2026-01-15 | 2026-01-15 14:30:00 CST | 补充时分秒 |
|
||||
| 14:30 | 2026-01-15 14:30:00 CST | 补充日期和时区 |
|
||||
| 昨天 | 2026-01-14 HH:MM:SS CST | 使用具体日期 |
|
||||
| 刚才 | 2026-01-15 14:28:00 CST | 记录精确时间 |
|
||||
|
||||
---
|
||||
|
||||
**规范创建时间**: 2026-01-15 07:45:00 ACDT
|
||||
**最后更新时间**: 2026-01-15 07:45:00 ACDT
|
||||
- 备注
|
||||
- 配置变更
|
||||
- YYYY-MM-DD HH:MM 操作记录
|
||||
|
||||
Reference in New Issue
Block a user