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
2026-10-31 22:21:07 +08:00
parent 7d47762303
commit 237631147a
29 changed files with 4013 additions and 3928 deletions
@@ -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 操作记录
@@ -0,0 +1,269 @@
# skills 详细内容
## 备注
"""
# 获取或创建日记笔记本
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` |
| 路径规范 | `/{合同类型}/{甲方简称}-{乙方简称}-{年份}` |
---
## 配置变更
**变更时间**: 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 操作记录
**操作时间**: YYYY-MM-DD HH:MM:SS TZ
**操作人**: qiudl / Claude
**操作类型**: 数据库操作 / 服务重启 / 配置变更 / 部署发布
**操作内容**: 简短描述
### 详细步骤
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
+6 -304
View File
@@ -5,9 +5,6 @@ metadata:
invocation: user-invoked
disable-model-invocation: true
---
# 企业微信集成技能
## 功能概述
### 消息推送
@@ -484,307 +481,6 @@ screenshot_and_insert("https://www.baidu.com", "YOUR_DOCID", "百度首页截图
---
## 通用函数封装
### 简单文本文档
适用于报告、记录、会议纪要等。使用符号标记章节。
```python
def create_simple_doc(doc_name: str, content: str) -> dict:
"""
创建简单文本文档
Args:
doc_name: 文档名称
content: 文档内容(使用【】标记章节)
Returns:
dict: {"docid": "xxx", "url": "https://..."}
Example:
content = '''项目周报
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
【本周完成】
1. 完成用户模块开发
2. 修复登录bug
【下周计划】
1. 开始订单模块
2. 编写测试用例
'''
result = create_simple_doc("2026年第5周周报", content)
"""
token = get_access_token()
# 1. 创建文档
create_url = f"https://qyapi.weixin.qq.com/cgi-bin/wedoc/create_doc?access_token={token}"
create_resp = requests.post(create_url, json={
"doc_type": 3,
"doc_name": doc_name
}).json()
if create_resp.get("errcode") != 0:
return create_resp
docid = create_resp["docid"]
doc_url = create_resp["url"]
# 2. 写入内容
update_url = f"https://qyapi.weixin.qq.com/cgi-bin/wedoc/document/batch_update?access_token={token}"
update_resp = requests.post(update_url, json={
"docid": docid,
"requests": [{
"insert_text": {
"text": content,
"location": {"index": 0}
}
}]
}).json()
return {
"errcode": update_resp.get("errcode", 0),
"docid": docid,
"url": doc_url
}
```
### 合同类文档(带标题样式)
适用于合同、协议等需要标题层级的正式文档。
```python
import time
def create_contract_doc(doc_name: str, sections: list) -> dict:
"""
创建带标题样式的合同文档
Args:
doc_name: 文档名称
sections: 内容列表,格式 [(文本, 标题级别), ...]
标题级别: 1=主标题, 2=章节标题, 0=正文
Returns:
dict: {"docid": "xxx", "url": "https://..."}
Example:
sections = [
("物流服务合同", 1),
("合同编号: WL-2026-0201", 0),
("", 0),
("甲方(托运方)", 2),
("公司名称: xxx公司", 0),
("", 0),
("第一条 服务内容", 2),
("1.1 服务类型:货物运输", 0),
("1.2 货物类型:xxx", 0),
]
result = create_contract_doc("物流服务合同-甲方与乙方", sections)
"""
token = get_access_token()
# 1. 创建文档
create_url = f"https://qyapi.weixin.qq.com/cgi-bin/wedoc/create_doc?access_token={token}"
create_resp = requests.post(create_url, json={
"doc_type": 3,
"doc_name": doc_name
}).json()
if create_resp.get("errcode") != 0:
return create_resp
docid = create_resp["docid"]
doc_url = create_resp["url"]
# 2. 倒序内容(因为每次在位置0插入)
reversed_sections = list(reversed(sections))
# 3. 分批插入(每批最多25个,留余量)
update_url = f"https://qyapi.weixin.qq.com/cgi-bin/wedoc/document/batch_update?access_token={token}"
batch_size = 25
for i in range(0, len(reversed_sections), batch_size):
batch = reversed_sections[i:i+batch_size]
requests_list = []
for text, level in batch:
para = {"elements": [{"text_run": {"content": text}}]}
if level > 0:
para["paragraph_style"] = {"heading_level": level}
requests_list.append({
"insert_paragraph": {
"location": {"index": 0},
"paragraph": para
}
})
resp = requests.post(update_url, json={
"docid": docid,
"requests": requests_list
}).json()
if resp.get("errcode") != 0:
return {
"errcode": resp.get("errcode"),
"errmsg": resp.get("errmsg"),
"docid": docid,
"url": doc_url
}
time.sleep(0.3) # 避免频率限制
return {
"errcode": 0,
"docid": docid,
"url": doc_url
}
def build_contract_sections(
title: str,
party_a: dict,
party_b: dict,
clauses: list,
signature: bool = True
) -> list:
"""
构建合同内容结构
Args:
title: 合同标题
party_a: 甲方信息 {"name": "", "code": "", "address": "", "phone": "", "legal_rep": ""}
party_b: 乙方信息,格式同上
clauses: 条款列表 [{"title": "第一条 xxx", "items": ["1.1 xxx", "1.2 xxx"]}, ...]
signature: 是否包含签章栏
Returns:
list: 可直接传给 create_contract_doc 的 sections
"""
sections = []
# 标题
sections.append((title, 1))
sections.append(("", 0))
# 甲方
sections.append(("甲方", 2))
if party_a.get("name"):
sections.append((f"公司名称: {party_a['name']}", 0))
if party_a.get("code"):
sections.append((f"统一社会信用代码: {party_a['code']}", 0))
if party_a.get("address"):
sections.append((f"地址: {party_a['address']}", 0))
if party_a.get("phone"):
sections.append((f"联系电话: {party_a['phone']}", 0))
if party_a.get("legal_rep"):
sections.append((f"法定代表人: {party_a['legal_rep']}", 0))
sections.append(("", 0))
# 乙方
sections.append(("乙方", 2))
if party_b.get("name"):
sections.append((f"公司名称: {party_b['name']}", 0))
if party_b.get("code"):
sections.append((f"统一社会信用代码: {party_b['code']}", 0))
if party_b.get("address"):
sections.append((f"地址: {party_b['address']}", 0))
if party_b.get("phone"):
sections.append((f"联系电话: {party_b['phone']}", 0))
if party_b.get("legal_rep"):
sections.append((f"法定代表人: {party_b['legal_rep']}", 0))
sections.append(("", 0))
# 条款
for clause in clauses:
sections.append((clause["title"], 2))
for item in clause.get("items", []):
sections.append((item, 0))
sections.append(("", 0))
# 签章
if signature:
sections.append(("签章", 2))
sections.append(("", 0))
sections.append((f"甲方(盖章): {party_a.get('name', '')}", 0))
sections.append(("法定代表人/授权代表:________________", 0))
sections.append(("日期:________________", 0))
sections.append(("", 0))
sections.append((f"乙方(盖章): {party_b.get('name', '')}", 0))
sections.append(("法定代表人/授权代表:________________", 0))
sections.append(("日期:________________", 0))
return sections
```
### 使用示例
#### 简化示例
```python
# 简化示例:使用占位符
party_a = {"name": "甲方公司名称", "code": "甲方税号"}
party_b = {"name": "乙方公司名称", "code": "乙方税号"}
clauses = [
{"title": "第一条 服务内容", "items": ["1.1 xxx", "1.2 xxx"]},
{"title": "第二条 服务期限", "items": ["2.1 xxx"]},
]
sections = build_contract_sections("合同标题", party_a, party_b, clauses)
result = create_contract_doc("合同文档名称", sections)
```
#### 完整示例
```python
# 完整示例:创建物流合同
party_a = {
"name": "重庆妗晨工贸有限公司",
"code": "91500104MA7EJTPA6D",
"address": "重庆市大渡口区跳磴镇海康路106号1-1",
"phone": "15213397998"
}
party_b = {
"name": "北京名风新能源科技有限公司",
"code": "91110106092440790K",
"legal_rep": "魏小健"
}
clauses = [
{
"title": "第一条 服务内容",
"items": [
"1.1 服务类型:货物运输配送服务",
"1.2 货物类型:今麦郎系列产品",
]
},
{
"title": "第二条 服务期限",
"items": [
"2.1 合同有效期:自 2026年2月1日 至 2027年1月31日",
]
},
{
"title": "第三条 运费标准",
"items": [
"3.1 运费标准:今麦郎产品 2.50 元/件",
"3.2 结算周期:月结",
]
}
]
# 构建并创建文档
sections = build_contract_sections("物流服务合同", party_a, party_b, clauses)
result = create_contract_doc("物流服务合同-妗晨与名风", sections)
print(f"文档链接: {result['url']}")
```
---
## 常见错误码
| 错误码 | 说明 | 解决方案 |
@@ -809,3 +505,9 @@ print(f"文档链接: {result['url']}")
| API 文档 | https://developer.work.weixin.qq.com/document/ |
| 调试工具 | https://developer.work.weixin.qq.com/devtool/interface |
| 管理后台 | https://work.weixin.qq.com/wework_admin/ |
## 详细内容
以下章节已移到 [references/details.md](references/details.md):
- 通用函数封装
@@ -0,0 +1,303 @@
# skills 详细内容
## 通用函数封装
### 简单文本文档
适用于报告、记录、会议纪要等。使用符号标记章节。
```python
def create_simple_doc(doc_name: str, content: str) -> dict:
"""
创建简单文本文档
Args:
doc_name: 文档名称
content: 文档内容(使用【】标记章节)
Returns:
dict: {"docid": "xxx", "url": "https://..."}
Example:
content = '''项目周报
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
【本周完成】
1. 完成用户模块开发
2. 修复登录bug
【下周计划】
1. 开始订单模块
2. 编写测试用例
'''
result = create_simple_doc("2026年第5周周报", content)
"""
token = get_access_token()
# 1. 创建文档
create_url = f"https://qyapi.weixin.qq.com/cgi-bin/wedoc/create_doc?access_token={token}"
create_resp = requests.post(create_url, json={
"doc_type": 3,
"doc_name": doc_name
}).json()
if create_resp.get("errcode") != 0:
return create_resp
docid = create_resp["docid"]
doc_url = create_resp["url"]
# 2. 写入内容
update_url = f"https://qyapi.weixin.qq.com/cgi-bin/wedoc/document/batch_update?access_token={token}"
update_resp = requests.post(update_url, json={
"docid": docid,
"requests": [{
"insert_text": {
"text": content,
"location": {"index": 0}
}
}]
}).json()
return {
"errcode": update_resp.get("errcode", 0),
"docid": docid,
"url": doc_url
}
```
### 合同类文档(带标题样式)
适用于合同、协议等需要标题层级的正式文档。
```python
import time
def create_contract_doc(doc_name: str, sections: list) -> dict:
"""
创建带标题样式的合同文档
Args:
doc_name: 文档名称
sections: 内容列表,格式 [(文本, 标题级别), ...]
标题级别: 1=主标题, 2=章节标题, 0=正文
Returns:
dict: {"docid": "xxx", "url": "https://..."}
Example:
sections = [
("物流服务合同", 1),
("合同编号: WL-2026-0201", 0),
("", 0),
("甲方(托运方)", 2),
("公司名称: xxx公司", 0),
("", 0),
("第一条 服务内容", 2),
("1.1 服务类型:货物运输", 0),
("1.2 货物类型:xxx", 0),
]
result = create_contract_doc("物流服务合同-甲方与乙方", sections)
"""
token = get_access_token()
# 1. 创建文档
create_url = f"https://qyapi.weixin.qq.com/cgi-bin/wedoc/create_doc?access_token={token}"
create_resp = requests.post(create_url, json={
"doc_type": 3,
"doc_name": doc_name
}).json()
if create_resp.get("errcode") != 0:
return create_resp
docid = create_resp["docid"]
doc_url = create_resp["url"]
# 2. 倒序内容(因为每次在位置0插入)
reversed_sections = list(reversed(sections))
# 3. 分批插入(每批最多25个,留余量)
update_url = f"https://qyapi.weixin.qq.com/cgi-bin/wedoc/document/batch_update?access_token={token}"
batch_size = 25
for i in range(0, len(reversed_sections), batch_size):
batch = reversed_sections[i:i+batch_size]
requests_list = []
for text, level in batch:
para = {"elements": [{"text_run": {"content": text}}]}
if level > 0:
para["paragraph_style"] = {"heading_level": level}
requests_list.append({
"insert_paragraph": {
"location": {"index": 0},
"paragraph": para
}
})
resp = requests.post(update_url, json={
"docid": docid,
"requests": requests_list
}).json()
if resp.get("errcode") != 0:
return {
"errcode": resp.get("errcode"),
"errmsg": resp.get("errmsg"),
"docid": docid,
"url": doc_url
}
time.sleep(0.3) # 避免频率限制
return {
"errcode": 0,
"docid": docid,
"url": doc_url
}
def build_contract_sections(
title: str,
party_a: dict,
party_b: dict,
clauses: list,
signature: bool = True
) -> list:
"""
构建合同内容结构
Args:
title: 合同标题
party_a: 甲方信息 {"name": "", "code": "", "address": "", "phone": "", "legal_rep": ""}
party_b: 乙方信息,格式同上
clauses: 条款列表 [{"title": "第一条 xxx", "items": ["1.1 xxx", "1.2 xxx"]}, ...]
signature: 是否包含签章栏
Returns:
list: 可直接传给 create_contract_doc 的 sections
"""
sections = []
# 标题
sections.append((title, 1))
sections.append(("", 0))
# 甲方
sections.append(("甲方", 2))
if party_a.get("name"):
sections.append((f"公司名称: {party_a['name']}", 0))
if party_a.get("code"):
sections.append((f"统一社会信用代码: {party_a['code']}", 0))
if party_a.get("address"):
sections.append((f"地址: {party_a['address']}", 0))
if party_a.get("phone"):
sections.append((f"联系电话: {party_a['phone']}", 0))
if party_a.get("legal_rep"):
sections.append((f"法定代表人: {party_a['legal_rep']}", 0))
sections.append(("", 0))
# 乙方
sections.append(("乙方", 2))
if party_b.get("name"):
sections.append((f"公司名称: {party_b['name']}", 0))
if party_b.get("code"):
sections.append((f"统一社会信用代码: {party_b['code']}", 0))
if party_b.get("address"):
sections.append((f"地址: {party_b['address']}", 0))
if party_b.get("phone"):
sections.append((f"联系电话: {party_b['phone']}", 0))
if party_b.get("legal_rep"):
sections.append((f"法定代表人: {party_b['legal_rep']}", 0))
sections.append(("", 0))
# 条款
for clause in clauses:
sections.append((clause["title"], 2))
for item in clause.get("items", []):
sections.append((item, 0))
sections.append(("", 0))
# 签章
if signature:
sections.append(("签章", 2))
sections.append(("", 0))
sections.append((f"甲方(盖章): {party_a.get('name', '')}", 0))
sections.append(("法定代表人/授权代表:________________", 0))
sections.append(("日期:________________", 0))
sections.append(("", 0))
sections.append((f"乙方(盖章): {party_b.get('name', '')}", 0))
sections.append(("法定代表人/授权代表:________________", 0))
sections.append(("日期:________________", 0))
return sections
```
### 使用示例
#### 简化示例
```python
# 简化示例:使用占位符
party_a = {"name": "甲方公司名称", "code": "甲方税号"}
party_b = {"name": "乙方公司名称", "code": "乙方税号"}
clauses = [
{"title": "第一条 服务内容", "items": ["1.1 xxx", "1.2 xxx"]},
{"title": "第二条 服务期限", "items": ["2.1 xxx"]},
]
sections = build_contract_sections("合同标题", party_a, party_b, clauses)
result = create_contract_doc("合同文档名称", sections)
```
#### 完整示例
```python
# 完整示例:创建物流合同
party_a = {
"name": "重庆妗晨工贸有限公司",
"code": "91500104MA7EJTPA6D",
"address": "重庆市大渡口区跳磴镇海康路106号1-1",
"phone": "15213397998"
}
party_b = {
"name": "北京名风新能源科技有限公司",
"code": "91110106092440790K",
"legal_rep": "魏小健"
}
clauses = [
{
"title": "第一条 服务内容",
"items": [
"1.1 服务类型:货物运输配送服务",
"1.2 货物类型:今麦郎系列产品",
]
},
{
"title": "第二条 服务期限",
"items": [
"2.1 合同有效期:自 2026年2月1日 至 2027年1月31日",
]
},
{
"title": "第三条 运费标准",
"items": [
"3.1 运费标准:今麦郎产品 2.50 元/件",
"3.2 结算周期:月结",
]
}
]
# 构建并创建文档
sections = build_contract_sections("物流服务合同", party_a, party_b, clauses)
result = create_contract_doc("物流服务合同-妗晨与名风", sections)
print(f"文档链接: {result['url']}")
```
---