Compare commits
6 Commits
786038d22e
...
master
| Author | SHA1 | Date | |
|---|---|---|---|
|
0f781f7b75 | ||
|
|
ba2c096323 | ||
|
|
687ab5ee28 | ||
|
|
55da2b74a4 | ||
|
|
1351371bd2 | ||
|
|
57b797196c |
3
.gitignore
vendored
3
.gitignore
vendored
@@ -41,6 +41,7 @@ Thumbs.db
|
||||
|
||||
# .claude
|
||||
.claude/
|
||||
|
||||
.agents/
|
||||
skills-lock.json
|
||||
#temp files
|
||||
temp/
|
||||
128
demo_scripts/check-mermaid.js
Normal file
128
demo_scripts/check-mermaid.js
Normal file
@@ -0,0 +1,128 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
const fs = require('fs');
|
||||
const { execSync } = require('child_process');
|
||||
const path = require('path');
|
||||
const os = require('os');
|
||||
|
||||
// 获取命令行传入的 Markdown 文件路径
|
||||
const fileArg = process.argv[2];
|
||||
if (!fileArg) {
|
||||
console.error('❌ 请提供 Markdown 文件路径。用法: node check-mermaid.js <file.md>');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const filePath = path.resolve(fileArg);
|
||||
const fileName = path.basename(filePath);
|
||||
|
||||
if (!fs.existsSync(filePath)) {
|
||||
console.error(`❌ 文件不存在: ${filePath}`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const content = fs.readFileSync(filePath, 'utf-8');
|
||||
|
||||
// 正则匹配 ```mermaid ... ``` 代码块，兼容 Windows(\r\n) 和 Linux(\n)
|
||||
const mermaidRegex = /```mermaid\r?\n([\s\S]*?)```/g;
|
||||
let match;
|
||||
let blockCount = 0;
|
||||
let errorCount = 0;
|
||||
|
||||
// 用于收集所有格式化后的错误报告块
|
||||
const errorReports = [];
|
||||
|
||||
while ((match = mermaidRegex.exec(content)) !== null) {
|
||||
blockCount++;
|
||||
|
||||
const fullMatch = match[0];
|
||||
const code = match[1];
|
||||
|
||||
// 1. 计算在 Markdown 文件中的绝对行号
|
||||
const textBeforeMatch = content.substring(0, match.index);
|
||||
const startLine = textBeforeMatch.split(/\r?\n/).length;
|
||||
const endLine = startLine + fullMatch.split(/\r?\n/).length - 1;
|
||||
|
||||
// 创建临时文件存放单个 Mermaid 代码
|
||||
const tmpFile = path.join(os.tmpdir(), `mermaid-check-${Date.now()}-${blockCount}.mmd`);
|
||||
fs.writeFileSync(tmpFile, code.trim());
|
||||
|
||||
try {
|
||||
// 调用 mmdc 进行静默渲染检查
|
||||
execSync(`npx mmdc -i "${tmpFile}" -o "${tmpFile}.svg" -q`, { stdio: 'pipe' });
|
||||
} catch (error) {
|
||||
errorCount++;
|
||||
|
||||
// 2. 净化报错信息：剔除底层执行堆栈
|
||||
const stderr = error.stderr ? error.stderr.toString() : error.message;
|
||||
const errorLines = stderr.split(/\r?\n/);
|
||||
const cleanErrorLines = [];
|
||||
|
||||
for (const line of errorLines) {
|
||||
if (line.trim().startsWith('at ') ||
|
||||
line.includes('Parser3.parseError') ||
|
||||
line.includes('fromText')) {
|
||||
break;
|
||||
}
|
||||
cleanErrorLines.push(line);
|
||||
}
|
||||
const cleanErrorOutput = cleanErrorLines.join('\n').trim();
|
||||
|
||||
// 3. 截断代码内容：最少3行，最多6行
|
||||
const codeLines = code.split(/\r?\n/).filter(l => l.trim() !== '');
|
||||
let displayCode = '';
|
||||
|
||||
if (codeLines.length <= 6) {
|
||||
displayCode = codeLines.join('\n');
|
||||
} else {
|
||||
const head = codeLines.slice(0, 3).join('\n');
|
||||
const tail = codeLines.slice(-3).join('\n');
|
||||
displayCode = `${head}\n ...\n ... (中间省略 ${codeLines.length - 6} 行) ...\n ...\n${tail}`;
|
||||
}
|
||||
|
||||
// 4. 组装单个错误的 Markdown 块
|
||||
errorReports.push(`### ❌ 错误 #${errorCount} (代码块 #${blockCount})
|
||||
|
||||
- **文档位置：** 第 \`${startLine}\` 行至第 \`${endLine}\` 行
|
||||
|
||||
#### 核心错误详情
|
||||
\`\`\`text
|
||||
${cleanErrorOutput}
|
||||
\`\`\`
|
||||
|
||||
#### 代码内容片段
|
||||
\`\`\`text
|
||||
${displayCode}
|
||||
\`\`\``);
|
||||
|
||||
} finally {
|
||||
// 清理临时文件
|
||||
if (fs.existsSync(tmpFile)) fs.unlinkSync(tmpFile);
|
||||
if (fs.existsSync(`${tmpFile}.svg`)) fs.unlinkSync(`${tmpFile}.svg`);
|
||||
}
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------------
|
||||
// 生成最终的 Markdown 报告输出
|
||||
// ------------------------------------------------------------------
|
||||
|
||||
if (errorCount > 0) {
|
||||
// 存在错误的情况
|
||||
console.log(`## 🚨 Mermaid 语法检查报告\n`);
|
||||
console.log(`**检查文件：** \`${fileName}\``);
|
||||
console.log(`**检查结果：** ❌ 发现 ${errorCount} 处语法错误 (共检测到 ${blockCount} 个代码块)\n`);
|
||||
console.log(`---\n`);
|
||||
console.log(errorReports.join('\n\n---\n\n'));
|
||||
|
||||
// 返回非零状态码，确保在 CI/CD 或 Git Hook 中能够阻断流程
|
||||
process.exit(1);
|
||||
} else {
|
||||
// 全部正确或没有代码块的情况
|
||||
console.log(`## 🎉 Mermaid 语法检查报告\n`);
|
||||
console.log(`**检查文件：** \`${fileName}\``);
|
||||
if (blockCount === 0) {
|
||||
console.log(`**检查结果：** ⚠️ 未检测到 Mermaid 代码块`);
|
||||
} else {
|
||||
console.log(`**检查结果：** ✅ 全部通过 (共检测到 ${blockCount} 个代码块)`);
|
||||
}
|
||||
process.exit(0);
|
||||
}
|
||||
482
demo_scripts/demo.md
Normal file
482
demo_scripts/demo.md
Normal file
@@ -0,0 +1,482 @@
|
||||
# Admin 用户物料清理数据流说明文档
|
||||
|
||||
## 概述
|
||||
|
||||
本文档详细说明 ERPAuto 系统中，Admin 用户执行物料清理操作时，被清理物料的完整获取流程、数据来源和处理链路。
|
||||
|
||||
## 核心结论
|
||||
|
||||
**Admin 用户清理的物料来源**：被清理的物料代码从数据库表 `dbo.MaterialsToBeDeleted` 中获取，根据 Admin 用户在 UI 界面选择的负责人（Manager）进行过滤。
|
||||
|
||||
---
|
||||
|
||||
## 数据流总览
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UI as CleanerPage (UI)
|
||||
participant Hook as useCleaner Hook
|
||||
participant API as Renderer API
|
||||
participant IPC as IPC Channel
|
||||
participant Service as ValidationService
|
||||
participant DB as Database
|
||||
|
||||
UI->>Hook: handleExecuteDeletion()
|
||||
Hook->>API: runCleanerExecution()
|
||||
API->>IPC: validation.getCleanerData({selectedManagers})
|
||||
|
||||
IPC->>Service: getCleanerData(userInfo, selectedManagers)
|
||||
|
||||
alt Admin User
|
||||
Service->>Service: loadMaterialCodesForCleaner()
|
||||
Service->>DB: SELECT MaterialCode FROM dbo.MaterialsToBeDeleted<br/>WHERE ManagerName IN (selectedManagers)
|
||||
DB-->>Service: materialCodes[]
|
||||
Service-->>IPC: {orderNumbers[], materialCodes[]}
|
||||
else Regular User
|
||||
Service->>DB: SELECT MaterialCode FROM dbo.MaterialsToBeDeleted<br/>WHERE ManagerName = username
|
||||
DB-->>Service: materialCodes[]
|
||||
Service-->>IPC: {orderNumbers[], materialCodes[]}
|
||||
end
|
||||
|
||||
IPC-->>API: cleanerData
|
||||
API->>IPC: cleaner.runCleaner({orderNumbers, materialCodes})
|
||||
IPC->>Service: CleanerApplicationService.runCleaner()
|
||||
Service->>UI: 执行清理 (ERP 删除)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 架构分层
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "渲染进程 (Renderer)"
|
||||
UI[CleanerPage.tsx]
|
||||
HOOK[useCleaner.ts]
|
||||
RAPI[renderer/api.ts]
|
||||
end
|
||||
|
||||
subgraph "主进程 (Main)"
|
||||
IPC_VAL[IPC: validation.getCleanerData]
|
||||
IPC_CLEAN[IPC: cleaner.runCleaner]
|
||||
VAS[ValidationApplicationService]
|
||||
CAS[CleanerApplicationService]
|
||||
ERP["CleanerService (ERP)"]
|
||||
end
|
||||
|
||||
subgraph "数据库 (Database)"
|
||||
MTBD[(dbo.MaterialsToBeDeleted)]
|
||||
DMPD[(dbo.DiscreteMaterialPlanData)]
|
||||
MTTD[(dbo.MaterialsTypeToBeDeleted)]
|
||||
end
|
||||
|
||||
UI --> HOOK
|
||||
HOOK --> RAPI
|
||||
RAPI --> IPC_VAL
|
||||
RAPI --> IPC_CLEAN
|
||||
IPC_VAL --> VAS
|
||||
IPC_CLEAN --> CAS
|
||||
VAS --> MTBD
|
||||
VAS --> DMPD
|
||||
VAS --> MTTD
|
||||
CAS --> ERP
|
||||
|
||||
style MTBD fill:#f9f,stroke:#333
|
||||
style MTTD fill:#f9f,stroke:#333
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 关键数据表
|
||||
|
||||
### 1. `dbo.MaterialsToBeDeleted` (核心来源表)
|
||||
|
||||
**作用**：存储所有被标记为待删除的物料代码及其负责人。
|
||||
|
||||
**表结构**：
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `ID` | int | 主键 |
|
||||
| `MaterialCode` | varchar | **物料代码 (被清理的目标)** |
|
||||
| `ManagerName` | varchar | 负责人姓名 |
|
||||
|
||||
**Admin 获取物料的 SQL 查询**：
|
||||
|
||||
```sql
|
||||
SELECT MaterialCode
|
||||
FROM dbo.MaterialsToBeDeleted
|
||||
WHERE ManagerName IN (@manager0, @manager1, ...)
|
||||
AND MaterialCode IS NOT NULL
|
||||
```
|
||||
|
||||
### 2. `dbo.MaterialsTypeToBeDeleted` (物料类型配置表)
|
||||
|
||||
**作用**：定义物料名称关键词与负责人的映射关系，用于自动分配负责人。
|
||||
|
||||
**表结构**：
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `MaterialName` | varchar | 物料名称关键词 |
|
||||
| `ManagerName` | varchar | 对应的负责人 |
|
||||
|
||||
**示例**：
|
||||
| MaterialName | ManagerName |
|
||||
|-------------|-------------|
|
||||
| "电阻" | "张三" |
|
||||
| "电容" | "李四" |
|
||||
|
||||
### 3. `dbo.DiscreteMaterialPlanData` (物料计划数据表)
|
||||
|
||||
**作用**：存储从 ERP 提取的完整物料计划数据，用于校验和展示物料详情。
|
||||
|
||||
**关键字段**：
|
||||
|
||||
- `MaterialCode` - 物料代码
|
||||
- `MaterialName` - 物料名称
|
||||
- `Specification` - 规格
|
||||
- `Model` - 型号
|
||||
- `SourceNo` - 订单号
|
||||
|
||||
---
|
||||
|
||||
## Admin 用户完整数据流
|
||||
|
||||
### 阶段 1: 校验 (Validation)
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "步骤 1: 用户触发的数据来源"
|
||||
A1[Admin 点击'数据校验']
|
||||
end
|
||||
|
||||
subgraph "步骤 2: 数据获取模式"
|
||||
A2{校验模式？}
|
||||
A21[Full Mode<br/>全量数据]
|
||||
A22[Filtered Mode<br/>筛选数据]
|
||||
end
|
||||
|
||||
subgraph "步骤 3: 数据库查询"
|
||||
A3[DiscreteMaterialPlanDAO]
|
||||
A31["queryAllDistinctByMaterialCode()"]
|
||||
A32["queryBySourceNumbersDistinct(orderNumbers)"]
|
||||
end
|
||||
|
||||
subgraph "步骤 4: 数据增强"
|
||||
A4[加载负责人信息]
|
||||
A41[加载 MaterialsTypeToBeDeleted<br/>关键词匹配]
|
||||
A42[加载 MaterialsToBeDeleted<br/>已标记记录]
|
||||
end
|
||||
|
||||
subgraph "结果"
|
||||
A5["ValidationResult[]<br/>包含 isMarkedForDeletion 标志"]
|
||||
end
|
||||
|
||||
A1 --> A2
|
||||
A2 -->|Full| A21
|
||||
A2 -->|Filtered| A22
|
||||
A21 --> A31
|
||||
A22 --> A32
|
||||
A31 --> A4
|
||||
A32 --> A4
|
||||
A4 --> A41
|
||||
A4 --> A42
|
||||
A4 --> A5
|
||||
|
||||
style A5 fill:#9f9,stroke:#333
|
||||
```
|
||||
|
||||
**Admin 特殊逻辑**：
|
||||
|
||||
- Admin 可以看到**所有负责人**的物料
|
||||
- UI 会显示 Manager 列下拉筛选器
|
||||
- Admin 默认选中所有 Manager
|
||||
|
||||
### 阶段 2: 保存删除计划 (可选)
|
||||
|
||||
用户在 UI 上勾选物料 → 点击"确认删除" → 数据写入 `MaterialsToBeDeleted` 表：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UI as 用户界面
|
||||
participant DAO as MaterialsToBeDeletedDAO
|
||||
participant DB as Database
|
||||
|
||||
UI->>DAO: upsertBatch(materials[])
|
||||
|
||||
loop 对每个物料
|
||||
DAO->>DB: MERGE INTO dbo.MaterialsToBeDeleted<br/>ON MaterialCode<br/>WHEN MATCHED UPDATE<br/>WHEN NOT MATCHED INSERT
|
||||
end
|
||||
|
||||
DB-->>DAO: 成功/失败统计
|
||||
DAO-->>UI: { total, success, failed }
|
||||
```
|
||||
|
||||
**SQL 逻辑**（MERGE UPSERT）：
|
||||
|
||||
```sql
|
||||
MERGE INTO dbo.MaterialsToBeDeleted AS target
|
||||
USING (VALUES (@MaterialCode, @ManagerName)) AS source (MaterialCode, ManagerName)
|
||||
ON target.MaterialCode = source.MaterialCode
|
||||
WHEN MATCHED THEN
|
||||
UPDATE SET ManagerName = source.ManagerName
|
||||
WHEN NOT MATCHED THEN
|
||||
INSERT (MaterialCode, ManagerName) VALUES (source.MaterialCode, source.ManagerName);
|
||||
```
|
||||
|
||||
### 阶段 3: 执行清理 (关键步骤)
|
||||
|
||||
这是 Admin 用户执行实际删除操作的核心流程：
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph "Renderer 层"
|
||||
S1["handleExecuteDeletion()"]
|
||||
S1-->S2["runCleanerExecution {selectedManagers}"]
|
||||
end
|
||||
|
||||
subgraph "获取清理数据 (主进程)"
|
||||
S2-->S3[ValidationApplicationService.getCleanerData]
|
||||
S3-->S4{用户类型？}
|
||||
|
||||
S4-->|Admin + selectedManagers| S5[loadMaterialCodesForCleaner<br/>Admin With Managers]
|
||||
S5-->S6[SELECT FROM MaterialsToBeDeleted<br/>WHERE ManagerName IN selectedManagers]
|
||||
|
||||
S4-->|Admin no managers| S7[Admin Without Managers]
|
||||
S7-->S8[SELECT FROM DiscreteMaterialPlanData<br/>WHERE SourceNo IN orderNumbers]
|
||||
|
||||
S4-->|普通用户 | S9[SELECT FROM MaterialsToBeDeleted<br/>WHERE ManagerName = username]
|
||||
end
|
||||
|
||||
subgraph "执行清理"
|
||||
S6-->S10["返回 materialCodes[]"]
|
||||
S8-->S10
|
||||
S9-->S10
|
||||
S10-->S11[CleanerApplicationService.runCleaner]
|
||||
S11-->S12[CleanerService.clean<br/>连接 ERP 执行删除]
|
||||
end
|
||||
|
||||
S12-->S13[清理完成报告]
|
||||
|
||||
style S5 fill:#ff9,stroke:#333
|
||||
style S6 fill:#f96,stroke:#333
|
||||
style S12 fill:#f99,stroke:#333
|
||||
```
|
||||
|
||||
**关键代码路径**：
|
||||
|
||||
```typescript
|
||||
// src/main/services/validation/validation-application-service.ts
|
||||
// loadMaterialCodesForCleaner() 方法
|
||||
|
||||
// Admin with selected managers:
|
||||
if (isAdmin && selectedManagers && selectedManagers.length > 0) {
|
||||
const materialCodes = await this.queryMaterialCodesByManagers(
|
||||
dbService,
|
||||
markedTableName, // dbo.MaterialsToBeDeleted
|
||||
selectedManagers
|
||||
)
|
||||
return materialCodes
|
||||
}
|
||||
|
||||
// Admin without selected managers (fallback):
|
||||
if (isAdmin) {
|
||||
if (orderNumbers.length === 0) {
|
||||
return [] // 无数据可处理
|
||||
}
|
||||
const materialDao = new DiscreteMaterialPlanDAO()
|
||||
const records = await materialDao.queryBySourceNumbersDistinct(orderNumbers)
|
||||
const materialCodes = [...new Set(records.map((r) => r.MaterialCode as string).filter(Boolean))]
|
||||
return materialCodes
|
||||
}
|
||||
```
|
||||
|
||||
### 阶段 4: ERP 删除执行
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant CAS as CleanerApplicationService
|
||||
participant Cleaner as CleanerService
|
||||
participant ERP as ERP System
|
||||
|
||||
CAS->>Cleaner: clean({orderNumbers, materialCodes})
|
||||
|
||||
loop 每个订单号
|
||||
Cleaner->>ERP: 登录 (一次)
|
||||
loop 每个物料代码
|
||||
Cleaner->>ERP: 查询物料计划
|
||||
alt 物料存在
|
||||
Cleaner->>ERP: 执行删除
|
||||
ERP-->>Cleaner: 删除结果
|
||||
else 物料不存在
|
||||
Cleaner-->>Cleaner: 跳过
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
Cleaner-->>CAS: CleanerResult
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Admin 用户的数据来源路径
|
||||
|
||||
整理出 Admin 用户获取物料的完整路径：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
Start[Admin 点击执行清理] --> Check{有 selectedManagers?}
|
||||
|
||||
Check -->|Yes| Path1[路径 1: MaterialsToBeDeleted 表]
|
||||
Path1 --> Q1["SELECT MaterialCode FROM MaterialsToBeDeleted<br/>WHERE ManagerName IN (selectedManagers)"]
|
||||
Q1 --> Merge[合并所有物料代码]
|
||||
|
||||
Check -->|No| Path2[路径 2: DiscreteMaterialPlanData 表]
|
||||
Path2 --> NeedProd{有共享 Production ID?}
|
||||
NeedProd -->|Yes| GetOrder[从共享 ID 解析订单号]
|
||||
GetOrder --> Q2["SELECT DISTINCT MaterialCode FROM DiscreteMaterialPlanData<br/>WHERE SourceNo IN (orderNumbers)"]
|
||||
Q2 --> Merge
|
||||
|
||||
NeedProd -->|No| Empty[返回空数组<br/>无法执行清理]
|
||||
|
||||
Merge --> Execute[传递给 CleanerService<br/>执行 ERP 删除]
|
||||
|
||||
style Path1 fill:#9f9,stroke:#333,stroke-width:2px
|
||||
style Path2 fill:#ff9,stroke:#333,stroke-width:2px
|
||||
style Empty fill:#f99,stroke:#333
|
||||
style Execute fill:#f96,stroke:#333,stroke-width:3px
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 关键代码位置参考
|
||||
|
||||
### 渲染层 (Renderer)
|
||||
|
||||
| 文件 | 函数 | 说明 |
|
||||
| ---------------------------------------- | ----------------------- | -------------------------- |
|
||||
| `src/renderer/src/pages/CleanerPage.tsx` | `handleExecuteDeletion` | 清理入口 |
|
||||
| `src/renderer/src/hooks/useCleaner.ts` | `handleExecuteDeletion` | 调用 `runCleanerExecution` |
|
||||
| `src/renderer/src/hooks/cleaner/api.ts` | `runCleanerExecution` | 先获取数据再执行清理 |
|
||||
|
||||
### 主进程层 (Main)
|
||||
|
||||
| 文件 | 类/函数 | 说明 |
|
||||
| ---------------------------------------------------------------- | ----------------------------------------------- | ---------------- |
|
||||
| `src/main/ipc/validation-handler.ts` | `VALIDATION_GET_CLEANER_DATA` | IPC 入口 |
|
||||
| `src/main/services/validation/validation-application-service.ts` | `getCleanerData`, `loadMaterialCodesForCleaner` | **核心逻辑** |
|
||||
| `src/main/services/cleaner/cleaner-application-service.ts` | `runCleaner` | 执行 ERP 清理 |
|
||||
| `src/main/services/erp/cleaner.ts` | `CleanerService.clean` | ERP 浏览器自动化 |
|
||||
|
||||
### 数据库层 (DAO)
|
||||
|
||||
| 文件 | 类 | 说明 |
|
||||
| ----------------------------------------------------------- | ------------------------- | ---------------------------- |
|
||||
| `src/main/services/database/materials-to-be-deleted-dao.ts` | `MaterialsToBeDeletedDAO` | `MaterialsToBeDeleted`表操作 |
|
||||
| `src/main/services/database/discrete-material-plan-dao.ts` | `DiscreteMaterialPlanDAO` | 物料计划数据查询 |
|
||||
|
||||
---
|
||||
|
||||
## 数据流状态图
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> 物料录入：用户在 UI 输入物料
|
||||
物料录入 --> 待校验：保存到 MaterialsToBeDeleted 表
|
||||
|
||||
待校验 --> 校验中：点击"数据校验"
|
||||
校验中 --> 已标记：通过关键词匹配负责人
|
||||
已标记 --> 待清理：用户勾选物料
|
||||
|
||||
待清理 --> 清理执行中：点击"执行清理"
|
||||
清理执行中 --> 清理完成：ERP 删除成功
|
||||
清理执行中 --> 部分失败：部分物料删除失败
|
||||
|
||||
清理完成 --> [*]
|
||||
部分失败 --> [*]
|
||||
|
||||
note right of 待清理
|
||||
Admin 可以查看和选择
|
||||
所有负责人的物料
|
||||
end note
|
||||
|
||||
note right of 清理执行中
|
||||
从 MaterialsToBeDeleted 表
|
||||
根据 selectedManagers 过滤
|
||||
获取要删除的物料代码
|
||||
end note
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 数据流对比：Admin vs 普通用户
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Admin 用户"
|
||||
A1[勾选多个 Manager]
|
||||
A2[SELECT FROM MaterialsToBeDeleted<br/>WHERE ManagerName IN selectedManagers]
|
||||
A3[获取所有选中负责人的物料]
|
||||
end
|
||||
|
||||
subgraph "普通用户"
|
||||
B1[只能看到自己的物料]
|
||||
B2[SELECT FROM MaterialsToBeDeleted<br/>WHERE ManagerName = username]
|
||||
B3[只能删除自己的物料]
|
||||
end
|
||||
|
||||
A1 --> A2 --> A3 --> Exec[执行清理]
|
||||
B1 --> B2 --> B3 --> Exec
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 常见问题解答
|
||||
|
||||
### Q1: **物料代码是如何被录入到 `MaterialsToBeDeleted` 表的？**
|
||||
|
||||
**A**: 有三种方式：
|
||||
|
||||
1. **用户手动勾选** → 在 CleanerPage 勾选物料 → 点击"确认删除" → `upsertBatch`
|
||||
2. **关键词自动匹配** → 校验时根据 `MaterialsTypeToBeDeleted` 配置自动分配负责人和标记
|
||||
3. **API 直接写入** → 其他服务调用 `materials.upsertBatch` IPC
|
||||
|
||||
### Q2: **Admin 如果不选 Manager 会怎样？**
|
||||
|
||||
**A**: Admin 可以不选 Manager，此时：
|
||||
|
||||
- 系统会尝试从"共享 Production ID"解析订单号
|
||||
- 然后从 `DiscreteMaterialPlanData` 表查询所有物料代码（不经过 `MaterialsToBeDeleted` 过滤）
|
||||
- 如果没有共享 Production ID，则返回空数组，无法执行清理
|
||||
|
||||
### Q3: **物料代码会在清理后被自动删除吗？**
|
||||
|
||||
**A**:
|
||||
|
||||
- ✅ **干运行模式**：不删除 ERP 数据，但会保留 UI 状态
|
||||
- ✅ **正式执行**：
|
||||
- ERP 中的物料计划被删除
|
||||
- `MaterialsToBeDeleted` 表中记录**不会被自动删除**（需要手动清理）
|
||||
|
||||
### Q4: **如何清理已删除的物料记录？**
|
||||
|
||||
**A**: Admin 可以在物料管理界面：
|
||||
|
||||
- 按 Manager 筛选
|
||||
- 批量删除已处理的物料记录
|
||||
- 调用 `materials.delete` IPC 接口
|
||||
|
||||
---
|
||||
|
||||
## 总结
|
||||
|
||||
Admin 用户执行清理时，被清理物料的来源路径：
|
||||
|
||||
1. **主要来源**: `dbo.MaterialsToBeDeleted` 表
|
||||
2. **过滤条件**: `ManagerName IN (selectedManagers)`
|
||||
3. **执行流程**:
|
||||
- 从数据库查询物料代码
|
||||
- 结合订单号列表
|
||||
- 通过 Playwright 连接 ERP 系统
|
||||
- 逐个物料执行删除操作
|
||||
|
||||
**关键点**：被清理的物料**必须**先在 `MaterialsToBeDeleted` 表中存在记录，并且其 `ManagerName` 与 Admin 选择的负责人匹配。
|
||||
93
skills/meeting-minutes/SKILL.md
Normal file
93
skills/meeting-minutes/SKILL.md
Normal file
@@ -0,0 +1,93 @@
|
||||
---
|
||||
name: meeting-minutes
|
||||
description: Transform raw audio-transcription documents into clean, structured meeting minutes. Use this skill whenever the user provides a meeting transcript — any file with timestamps and speaker labels (说话人1 / Speaker 1), ASR/speech-to-text output, 转写结果, 录音转写 — and asks to organize, summarize, or 整理 it into 会议记录 / 会议纪要 / meeting minutes / action items. Also trigger when the user uploads a transcription of a meeting, review, training session, interview, or discussion and just says "整理一下" or "帮我总结", even without the word "会议记录". Do NOT use for writing minutes from scratch (no transcript) or for translating transcripts.
|
||||
---
|
||||
|
||||
# 录音转写 → 会议纪要
|
||||
|
||||
把口语化、带噪声的录音转写文档，整理成一份**详尽但不啰嗦**的正式会议纪要：所有实质信息（决议、数字、责任人、时限、分歧、疑点）一条不丢，所有口语噪声（重复、口头禅、寒暄、跑题碎语）一句不留。
|
||||
|
||||
成品的衡量标准：一个没参会的人读完纪要，能准确知道**会上定了什么、为什么这么定、还有什么没定、接下来谁在什么时间要做什么**。
|
||||
|
||||
## 工作流程
|
||||
|
||||
### 第 1 步：完整读取转写文件
|
||||
|
||||
**必须读完全文才能动笔。** 会议的决议常常在中途被推翻重定（先定方案 A，结尾改成 A+B 并存），只读开头或抽样阅读会把中间结论当成最终决议，这是此类任务最严重的错误。
|
||||
|
||||
- 先 `wc -c` / `wc -l` 探明文件大小，再按**行**分块读取（如 `sed -n '1,300p'`），逐块读完全部内容。
|
||||
- 中文转写是多字节 UTF-8，**不要用 `head -c` 等按字节截断的方式读取**，会切断字符导致输出乱码报错；始终按行读取。
|
||||
- 文件可能是 CRLF 行尾，属正常现象，无需处理。
|
||||
|
||||
### 第 2 步：边读边积累四类素材
|
||||
|
||||
读的过程中持续记录，读完即可直接成文：
|
||||
|
||||
1. **元数据**：源文件名、音频时长、说话人数量、分句数量（转写文件头部通常自带）。
|
||||
2. **同音误写词表**：见第 3 步。
|
||||
3. **说话人身份线索**：见第 4 步。
|
||||
4. **内容骨架**：议题切换点、每个议题下的讨论脉络、当场形成的决议（含被推翻的中间结论）、提到的待办（谁、做什么、什么时限）、被点名的人和精确数字。
|
||||
|
||||
### 第 3 步：同音误写校正（中文转写的核心难点）
|
||||
|
||||
方言口音和专业术语会让 ASR 产生大量同音/近音误写，且**同一个词在全文中会被写成多种错法**。典型规律：
|
||||
|
||||
- 专业缩写被写成日常词：BOM → "报幕/保姆/报模/爆品/泡沫/放牧"；VLOOKUP → "维鲁卡普"
|
||||
- 行业术语被写成同音常用词：接头→"截图"、螺纹→"论文"、量程→"量产/量成/量层"、选型→"血型/雪凝/选曲"、模板→"木板"、径向/轴向→"镜像/进项/主项"
|
||||
- 人名时对时错："郑工"被写成"正宫/正工"
|
||||
|
||||
处理规则：
|
||||
|
||||
- 同一上下文反复出现、读不通的词，按行业语境推断真实词义，**全文统一校正**。判断依据是上下文自洽：如果把"报幕"读成 BOM 后全文每一处都通顺，即可确认。
|
||||
- 在纪要开头用一段引述（blockquote）**集中声明校正对照**（"报幕/保姆"实为 BOM 等），让读者知道整理者做过什么，也便于核对。
|
||||
- **无法确认的专有名词（人名、系统名、工具名）不要硬猜**：模糊处理或标注"（名称待确认）"，并在交付时提醒用户核对。宁可标注疑点，不可编造确定性。
|
||||
|
||||
### 第 4 步：说话人身份归属（谨慎原则）
|
||||
|
||||
- 只依据**转写内部证据**归属身份：A 反复称呼 B 为"郑工"，则 B 是郑工；某人说"刘凯还有 7 个没做"且另一人应答"对，都快了"，则应答者**疑似**刘凯。
|
||||
- 证据充分的写实名（如：说话人 1，会中被称"郑工"）；证据单薄的加"疑似"；没有证据的保留"说话人 N"编号。
|
||||
- 在基本信息或正文中自然带出主持人、主讲人等**角色**（谁在部署工作、谁在演示、谁在记录待办），角色比名字更重要。
|
||||
- 会中被提及但未必在场的人名（被点名负责某事的人）照实写入待办事项。
|
||||
|
||||
### 第 5 步：按模板组织成文
|
||||
|
||||
整体结构和逐节写法**严格参照 `references/format-template.md`**（必读），成文前对照 `references/example.md` 中的真实范例校准颗粒度和语感。骨架为：
|
||||
|
||||
1. 标题：`# 会议纪要：<一句话概括的会议主题>`
|
||||
2. 会议基本信息（表格）+ 转写质量校正声明（blockquote）
|
||||
3. 正文若干部分：**按会议实际脉络划分议题章节**，不是按时间流水账，也不是套死固定章节数
|
||||
4. 会议总结与决议汇总（编号列表，关键决议加粗）
|
||||
5. 待办事项（表格：# / 事项 / 责任人 / 时限或备注）
|
||||
|
||||
### 第 6 步：交付
|
||||
|
||||
- 输出为 Markdown 文件，命名 `会议纪要_<会议日期>_<一句话概括的会议主题>.md`（日期取自源文件名或转写内容），保存到工作目录或用户指定位置，日期格式：`yyyy-MM-dd`。
|
||||
- 聊天回复保持简短：两三句概括会议规模与核心议题，**明确提醒用户核对**同音校正后的人名与专业术语，邀请反馈修订。不要在聊天里复述纪要内容。
|
||||
|
||||
## 风格红线（"详尽但不啰嗦"的具体含义）
|
||||
|
||||
**必须保留（详尽）：**
|
||||
|
||||
- 每一条实质决议、原则、要求，以及它的**理由**（"必须 1:1 配置油品，否则账实不符"——理由让纪要可信、可执行）
|
||||
- 精确数字、数量、时限、责任人（"刘凯尚余 7 个""下月初至中旬高勇检查"）
|
||||
- **决议的演变过程**：核心争论先呈现各方案的优缺点（适合用对比表格），再写表决与最终决议；会中先定后改的，最终决议为准、但要写明"经讨论改为"
|
||||
- 分歧与遗留问题：谁提出了什么顾虑、当场未解决的问题、"会后研究"的事项
|
||||
- 提出的疑点、特殊情况、边界条件（"径向件可代用于轴向，反之不可"）
|
||||
|
||||
**必须删除（不啰嗦）：**
|
||||
|
||||
- 全部口语噪声：语气词、重复、口吃式赘语（"那个那个""都都都"）、寒暄、应答碎语（"嗯""对头""好"）
|
||||
- 操作演示中的现场琐碎（"你打开了没""我看下是哪个文件"），只留演示所传达的**功能逻辑和操作流程**
|
||||
- 与议题无关的插话和跑题
|
||||
|
||||
**叙述纪律：**
|
||||
|
||||
- 严格区分四种性质并用措辞体现：**已形成决议** / **讨论中的观点** / **个人建议**（"主持人建议……"）/ **遗留待研究**
|
||||
- 只写转写中有的内容，不补充转写外的背景知识，不替会议做它没做的结论
|
||||
- 加粗只用于关键决议、关键约束、关键数字，宁少勿滥
|
||||
- 用转写的原语言写作（中文转写→中文纪要）；正文以陈述句为主，结构化信息（基本信息、方案对比、待办）用表格
|
||||
|
||||
## 参考文件
|
||||
|
||||
- `references/format-template.md` — 逐节模板与写法要点，**成文前必读**
|
||||
- `references/example.md` — 一份完整真实范例（制造业 BOM 工作会），用于校准详略与语感
|
||||
148
skills/meeting-minutes/references/example.md
Normal file
148
skills/meeting-minutes/references/example.md
Normal file
@@ -0,0 +1,148 @@
|
||||
# 完整范例：制造业 BOM 工作会纪要
|
||||
|
||||
> 本文件是一份真实转写（83 分钟、9 名说话人、1124 条分句、川渝口音、大量同音误写）整理出的成品纪要，是本 skill 风格的基准。注意学习它的：议题章节如何跟随会议脉络、争论如何用对比表呈现、决议演变如何表述（先定单一方案、后改为两案并存）、待办如何落到人与时限、疑点如何标注。
|
||||
|
||||
---
|
||||
|
||||
# 会议纪要：BOM 维护工作部署暨"BOM 新增物料小工具"培训会
|
||||
|
||||
## 一、会议基本信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 会议时间 | 2026 年 6 月 3 日 15:45 起，时长约 83 分钟 |
|
||||
| 记录来源 | 会议录音转写（源文件：2026年06月03日 15点45分.mp3，共 1124 条分句） |
|
||||
| 参会人数 | 9 人（转写标记为说话人 1–9） |
|
||||
| 主持人 | 说话人 1（会中被称"郑工"，负责工作部署与总结） |
|
||||
| 主讲/演示 | 说话人 4（信息化/小工具开发人员，负责工具演示与改造） |
|
||||
| 会议主题 | 现场 BOM 维护工作要求部署；信息化"BOM 新增物料小工具"培训、问题讨论与改进决议 |
|
||||
|
||||
> 说明：原始转写因方言口音存在大量同音误写（如"报幕/保姆/爆品"实为 **BOM**、"截图"实为**接头**、"论文"实为**螺纹**、"血型/雪凝"实为**选型**、"木板"实为**模板**、"量产/量成"实为**量程**、"维鲁卡普"实为 **VLOOKUP** 等），本纪要已按上下文统一校正。个别人名、工具名称无法完全确认处已作模糊处理。
|
||||
|
||||
---
|
||||
|
||||
## 二、第一部分：BOM 维护工作部署与要求（主持人）
|
||||
|
||||
1. **弹性元件 BOM 优先完成**：当前优选工作中，弹性元件部分必须首先做完、做扎实，不能马虎，否则会造成很大问题。接头部分目前配不完，可随时间推移在后续逐步补充更新。
|
||||
2. **线下 BOM（物料表）必须建立**，其用途包括：
|
||||
- 生产现场遇到物料缺失、错误或不便使用现场 BOM 时，依靠线下 BOM 修改订单计划、备料计划；
|
||||
- 生产订单上没有挂靠 BOM 的，需通过线下 BOM 导入采购（购买）计划，便于生产端快速处理；
|
||||
- 线下 BOM 灵活、约束少，简单处理即可快速供生产使用，因此本版必须做对、做准确。
|
||||
3. **线上 BOM 完成进度与时限**：刘凯处尚余 7 个（已接近完成），小左已完成，主持人处尚余 20 余个。未完成人员须尽快完成；预计下月初至中旬高勇方面将进行检查复核。
|
||||
4. **线上 BOM 编制原则**：
|
||||
- 必须把**指针**和**包装物**加入 BOM；
|
||||
- 落实核对物料，检查有无错漏；
|
||||
- 耐震表油品必须按 **1:1** 配置，不得随意抛减用量，否则会造成账上无数、实物却存在的账实不符问题，编制时务必仔细检查。
|
||||
5. **配料统一原则**：做现场 BOM 时，所用**弹簧管物料必须配齐**；若不配齐，后续更新线上 BOM 的节拍会非常频繁。
|
||||
6. **BOM 数据与选型数据必须一一匹配**：选型端有的，BOM 端必须有；宁可 BOM 数据范围做大，**选型数据不能大于 BOM 数据**，否则会出现选型选得出、BOM 推不出（缺料）的情况。
|
||||
7. **责任清单**：每人维护的现场 BOM 需建立清单，生产端发现问题时可据此指定责任人处理。
|
||||
|
||||
---
|
||||
|
||||
## 三、第二部分："BOM 新增物料小工具"培训与演示（说话人 4 主讲）
|
||||
|
||||
### 3.1 工具定位与基本操作
|
||||
|
||||
- 工具面向**现场 BOM 维护人员**，包含两大功能：① 新增**过程连接（接头）**物料；② 新增**量程范围（弹性元件）**物料。
|
||||
- 操作流程：打开文件 → **加载本人负责的型号** → 选择处理类型（过程连接 / 量程范围）→ 填入规格值 → 点击"数据处理" → 核对结果 → 点击"提交"，数据即写入 BOM 并保存。
|
||||
- 结果界面以颜色区分：**绿色 = 本次新增物料，蓝色 = 所参照的模板，黄色 = 发生变化的数据**；提交后行号自动全部重排。
|
||||
- 现场以 YBF 型号为例演示了新增 M14 过程连接（系统按径向低压/径向高压/轴向低压/轴向高压自动生成四类接头），并实际提交了一条测试数据验证写入效果。
|
||||
|
||||
### 3.2 模板机制（现行逻辑）
|
||||
|
||||
- 系统将该型号下与接头相关的物料自动提取并分类，**每一类型默认取最后一条物料作为模板**，复制其全部选择条件，仅将过程连接规格替换为新值（与人工新增逻辑一致）。
|
||||
- 自动判断的模板不一定正确，用户可通过"是/否"手动改选正确模板；**每个型号只需甄别一次**，确认后系统记忆，后续不再提示。
|
||||
- 两件式表只需新增**紧固接头**：首次处理时将不需要的类别置"否"即可，之后不再出现；如确需新增其他类别，再手动开启。
|
||||
|
||||
### 3.3 培训中提出的问题与讨论
|
||||
|
||||
1. **新增量程须先查映射**：C 型管加 U 型管在选型表中共有 44 个标准量程。新增量程前必须先与**量程映射表**核对——若已有对应/可替代关系则不得新增，应通过映射替代；确无对应关系方可加入选型，同时必须通知技术中心同步录入（映射关系由技术中心管理），否则选型仍然出不来。映射表由小朱提供给说话人 4，工具中将加入自动核对功能。
|
||||
2. **接头识别逻辑**：按物料名称含"接头"判断不可靠（存在命名不叫接头的接头、紧固接头与普通接头并存等情况），讨论认为按**选择条件中含过程连接（结合量程范围）**判断更准确；但包装盒等也带过程连接（分大小螺纹），两件式情形需做特殊处理。
|
||||
3. **下拉框体验**：加载型号后的下拉清单显示条数太少，维护型号多的人操作不便。要求将下拉框加长/加大或改为旁侧清单展示，说话人 4 承诺优化。
|
||||
4. **查重功能**：演示中发现已存在的规格（如 M14、M20F）再次新增时系统未报错。确定**螺纹规格与量程规格新增时均须增加查重校验**，已有则提示、不得重复添加，避免 BOM 推出重复物料。
|
||||
5. **测试数据清理**：工具早期实验写入的数据已污染演示表，说话人 4 当场承诺重新复制一份干净数据，活动结束后各自的旧数据也要收掉。
|
||||
|
||||
---
|
||||
|
||||
## 四、第三部分：接头选择条件生成方式之争（核心议题）
|
||||
|
||||
### 4.1 两条技术路线
|
||||
|
||||
| | 路线一：模板模式（现行） | 路线二：弹性元件模式（郑工方案） |
|
||||
| --- | --- | --- |
|
||||
| 原理 | 参照既有物料模板复制选择条件 | 不依赖模板；为接头指定弹簧管类型（C 型管/螺旋管），自动读取 BOM 页中对应弹性元件的全部选择条件（量程范围等）融合生成 |
|
||||
| 优点 | 前期轻松、马上可用 | 后期一劳永逸，无需逐条人工甄别"哪个模板量程最全" |
|
||||
| 缺点 | 每个型号首次都要人工甄别模板，型号多、条件多时"看不全、判不准"，长期工作量大 | 前期基础数据准备痛苦；若 BOM 页弹性元件量程本身做少了（如标准 20 个只做了 18 个），会跟着做错；且界面只呈现最终结果，看不到全部接头明细 |
|
||||
|
||||
### 4.2 配套问题讨论
|
||||
|
||||
- **选型约束归属**：采用路线二意味着 BOM 数据做大，必须依靠选型端（平台配置方法参数值表中的约束条件）收口。会议统一思想：**选型数据收紧约束、BOM 数据放大**——BOM 端不管"配不配得起"，能否下单由选型约束决定，选得出即推得出。
|
||||
- 现已出现绕过选型乱选的问题（如 1.6 级被直接选成 2.5 级），虽 BOM 推出的料是对的，但产品做不出来，更说明选型端约束必须维护起来；目前各人已陆续在选型中补加约束。
|
||||
- 螺纹与量程的匹配约束（某螺纹可用到多少压力以下）此前普遍未做。难点在选型页量程单位多达五六种，人工换算工作量大。说话人 4 提出后续配套：建立**量程代码—实际值对照表**并统一单位（如统一换算为 MPa），再做小工具按范围自动筛出符合的量程代码、生成约束条件；同时提供**BOM 与选型匹配性、量程完整性验证工具**。
|
||||
- **径向/轴向问题（说话人 3 提出）**：部分物料只有径向、没有轴向（径向件可代用于轴向、仅偏长，反之不可），库房现状即如此，需补数据；常规 C 型管量程是全的，特殊量程"以现有为准"。决议：在弹簧管**物料名称中加入识别标识**，分三类——不分径轴向的统一叫"弹簧管"，特殊的分别叫"径向弹簧管""轴向弹簧管"，正常不分的保持原样。
|
||||
- 对于按安装/设计形式（如 A0/B0 流程代码）约束管子的既有做法，存在同类型号用管不同、仅靠名称分径轴向区分不开（还有一体式/两体式之别）的特殊情况。
|
||||
|
||||
### 4.3 决议
|
||||
|
||||
经举手表决并综合讨论，**两种模式同时保留、由用户在工具中自行点选**：常规情形推荐采用弹性元件（弹簧管）模式以求长效；特殊型号（径轴向不全等）继续可用模板模式，不强求统一，"目的是把新物料加进去，而不是为了用某个工具"。
|
||||
|
||||
---
|
||||
|
||||
## 五、第四部分：量程范围新增功能讨论
|
||||
|
||||
1. 量程范围新增的处理分两部分，其中弹性元件物料的新增逻辑与过程连接类似；前提是**量程对照表必须先行规定完善**。
|
||||
2. **管子类型改为手动指定**：同一量程在不同型号下管型不同（如电接点型号 4 MPa 用 C 型管、常规 4 MPa 用螺旋管），自动判断不可靠，恢复早期版本的手动指定方式。
|
||||
3. **高压/低压同样改为手动指定**。现行自动逻辑为：统计该物料选择条件内各量程落在高/低压区间的"得分"，多者胜出（不按名称判断，可避开"中压接头"等命名问题；机芯尤其依赖此逻辑，因机芯名称分不出高低压且量程跨高低压两区）。判断错误时用户可手动改正并刷新模板，且只需选择一次。考虑到特殊情况（如部分订单指定用低压机芯出高压数据，需用户自行选择），最终仍决定以手动指定为准。
|
||||
4. **输入框拆分**：现版本中过程连接规格与量程规格共用同一输入单元格、靠类型选择区分；决定改为**两个独立输入框**，各管各的类型，程序上无实现障碍。
|
||||
5. **组合接头处理原则（主持人要求）**：类似 VCR 这种一个接头带三四个小零件的，今后新增时尽量做成**部件**——在 BIP 中将部件设为虚项、搭好部件 BOM，推出来即为散件，报表中以部件形式存在，避免逐零件维护的麻烦。
|
||||
|
||||
---
|
||||
|
||||
## 六、第五部分：线下 BOM 制作方法与经验分享（主持人）
|
||||
|
||||
- 线下 BOM 已基本做好，将发给大家参考；其制作远比线上 BOM 简单，工作量不大。
|
||||
- **一表多型号**：只要弹性元件（及机芯）通用，多个型号可合在一张表内做（示例：YT7-100 一张表覆盖 531、541、631、533、B0533、BT533、ZT521 及特殊单位、深圳地铁等型号），在同一表内为各型号划分独立区域并各自约束即可。
|
||||
- **关键技能与规则**：
|
||||
- 熟练使用 **VLOOKUP** 查询函数；通过增加辅助列等手段保证查询条件**唯一**，结果才正确；
|
||||
- 量程配接头建议采用简洁形式（参照主持人做法，避免过于复杂的搭法），便于后续取条件；
|
||||
- 设置**低压/高压分界线**，相同接头段可直接引用公式（如 MAX 段接头与 M01 接头一致时公式直接等于对应单元格），减少重复维护；
|
||||
- 注意**按量程段拆分**：如 10–60 MPa 段管坯用 F5 材料、100–250 MPa 段用 F7，理论上接头亦应随段不同而区分，目前虽未细分，编表时务必分段处理，不能混在一段；
|
||||
- 电接点型号因 10/16/25 MPa 用细管、与其他管不同，须单独建表，不能并入通用表；
|
||||
- **公用物料放变量库，专用物料做进各自报表**（如各型号配套的壳、罩、玻璃等在变量库中填写完整），读取结果即可保证正确，且便于维护；
|
||||
- YXH 之所以单独拆出，是因其 C 型管制造工艺及机芯与通用型号不同。
|
||||
- 第二版 BOM 的更新节拍理论上不应很多；若更新仍然频繁，应反思是否弹簧管等基础物料没有配全。
|
||||
|
||||
---
|
||||
|
||||
## 七、会议总结与决议汇总
|
||||
|
||||
主持人总结：本次会议历时约两小时，完成了信息化"BOM 新增物料小工具"（含新增接头物料、新增弹簧管物料两大功能）的培训，并形成以下整改决议：
|
||||
|
||||
1. 接头物料新增**增加"以 BOM 页弹性元件作为配用条件"的新模式**，同时**保留点选模板模式**，两种模式由用户自行选择；
|
||||
2. **螺纹规格新增增加查重功能**（已有则不再添加，防止 BOM 推出重复螺纹）；
|
||||
3. **量程范围新增同样增加查重功能**；
|
||||
4. 量程范围与过程连接的**输入框改为两个独立输入框**；
|
||||
5. **管子类型（C 型管/螺旋管）改为手动指定**；
|
||||
6. **高压/低压属性改为手动指定**；
|
||||
7. 研究在工具页面**增加一键打开导入上传小程序（exe）的按钮**（VBA 可操作 exe，此前已有实验基础，评估可实现）；
|
||||
8. 弹簧管物料名称增加**径向/轴向标识**（弹簧管 / 径向弹簧管 / 轴向弹簧管三类）；
|
||||
9. 选型端约束条件持续维护收紧，BOM 端放大；信息化后续配套量程对照、约束生成及 **BOM—选型匹配验证工具**。
|
||||
|
||||
---
|
||||
|
||||
## 八、待办事项
|
||||
|
||||
| # | 事项 | 责任人 | 时限/备注 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 按第七节决议 1–6 完成小工具改造并交付 | 说话人 4（信息化） | **本周内** |
|
||||
| 2 | 研究"一键打开导入上传小程序"按钮的可行性并实现 | 说话人 4 | 会后研究 |
|
||||
| 3 | 重新复制干净的演示/基础数据，清理早期实验数据 | 说话人 4 | 已当场处理，会后复核 |
|
||||
| 4 | 将量程映射关系表发给说话人 4，用于工具自动核对 | 小朱 | 尽快 |
|
||||
| 5 | 完成各自剩余线上 BOM（刘凯 7 个、主持人 20 余个等） | 相关维护人员 | 下月初至中旬前（高勇检查节点前） |
|
||||
| 6 | 线上 BOM 补充指针、包装物，核对物料，耐震表油品按 1:1 配置 | 全体 BOM 维护人员 | 编制过程中执行 |
|
||||
| 7 | 弹簧管名称按三类标识补充径向/轴向；径轴向缺失物料补数据 | 相关维护人员 | 持续 |
|
||||
| 8 | 新增量程前对照映射表核查，确需新增的同步通知技术中心录入 | 各维护人员/技术中心 | 长期规则 |
|
||||
| 9 | 选型端约束条件（含螺纹—量程匹配）持续补充维护 | 各维护人员 | 长期 |
|
||||
| 10 | 工具下发后投入使用，统计使用前后耗时、量化提效成果 | 全体使用人员 | 持续；成果用于向北京等单位推广 |
|
||||
| 11 | 建立各人现场 BOM 责任清单 | 全体维护人员 | 尽快 |
|
||||
| 12 | 将线下 BOM 样表发给大家，各自参照制作线下 BOM | 主持人 / 全体 | 尽快 |
|
||||
105
skills/meeting-minutes/references/format-template.md
Normal file
105
skills/meeting-minutes/references/format-template.md
Normal file
@@ -0,0 +1,105 @@
|
||||
# 会议纪要逐节模板与写法要点
|
||||
|
||||
以下骨架中，第 2、4、5 节为固定结构；第 3 节（正文）的章节数量和标题完全跟随会议实际内容。占位符用 `<>` 表示。
|
||||
|
||||
---
|
||||
|
||||
## 1. 标题
|
||||
|
||||
```markdown
|
||||
# 会议纪要：<会议主题，一句话，体现"做了什么事">
|
||||
```
|
||||
|
||||
主题要具体：写"BOM 维护工作部署暨'BOM 新增物料小工具'培训会"，不写"工作会议"。若会议有两条主线（如"部署 + 培训"），标题用"暨"连接。
|
||||
|
||||
## 2. 会议基本信息 + 转写质量声明
|
||||
|
||||
```markdown
|
||||
## 一、会议基本信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 会议时间 | <日期 + 开始时间>，时长约 <N> 分钟 |
|
||||
| 记录来源 | 会议录音转写（源文件：<文件名>，共 <N> 条分句） |
|
||||
| 参会人数 | <N> 人（转写标记为说话人 1–N） |
|
||||
| 主持人 | 说话人 <N>（<身份证据，如：会中被称"郑工"，负责工作部署与总结>） |
|
||||
| 主讲/演示 | 说话人 <N>（<角色描述>） |
|
||||
| 会议主题 | <一到两句话> |
|
||||
|
||||
> 说明：原始转写因<方言口音/专业术语>存在大量同音误写（如"<误写1/误写2>"实为 **<正确词>**、……），本纪要已按上下文统一校正。个别人名、工具名称无法完全确认处已作模糊处理。
|
||||
```
|
||||
|
||||
要点：
|
||||
|
||||
- 表格行可按实际情况增删（没有明显主讲人就删掉该行）。
|
||||
- 校正声明列举**最高频的 5–8 组**误写即可，不必穷举；这段话同时起到免责和提示核对的作用。
|
||||
|
||||
## 3. 正文：按会议脉络分部分
|
||||
|
||||
```markdown
|
||||
## 二、第一部分：<议题名>（<主导者角色>）
|
||||
|
||||
## 三、第二部分：<议题名>（<主导者> 主讲）
|
||||
|
||||
### 3.1 <子议题>
|
||||
### 3.2 <子议题>
|
||||
...
|
||||
```
|
||||
|
||||
划分原则与写法：
|
||||
|
||||
- **跟随会议的真实脉络**：开场部署 → 培训演示 → 争论 → 决议 → 经验分享……有几段写几段，常见 3–6 个部分。每部分标题点明议题，括号注明主导者。
|
||||
- 部署/要求类内容：用编号列表，一条一个要求，**要求 + 理由**写在同一条里。
|
||||
- 培训/演示类内容：分"定位与基本操作 / 机制说明 / 提出的问题与讨论"等小节；操作流程压缩成一条箭头链（打开 → 加载型号 → 填规格 → 数据处理 → 提交）。
|
||||
- **核心争论单独成章**，内部结构固定为三段：
|
||||
1. 各方案对比表（行：原理 / 优点 / 缺点；列：各方案，并注明提出人）
|
||||
2. 配套问题讨论（编号或加粗短语开头的列表）
|
||||
3. `### 决议`（明确写出表决方式和最终结论；若结论是折中或两案并存，写清楚适用边界）
|
||||
- 经验分享类内容：提炼成可执行的规则清单（"关键技能与规则"），保留具体例子作括号内示例。
|
||||
- 每个实质观点尽量带上下文中的**具体例子**（"如 1.6 级被直接选成 2.5 级"），例子是纪要可读性的来源。
|
||||
|
||||
## 4. 会议总结与决议汇总
|
||||
|
||||
```markdown
|
||||
## <N>、会议总结与决议汇总
|
||||
|
||||
<主持人总结时怎么说就怎么概括>：本次会议历时约 <X>，完成了 <主线一>，并形成以下整改决议：
|
||||
|
||||
1. <决议一，关键词加粗>；
|
||||
2. <决议二>；
|
||||
...
|
||||
```
|
||||
|
||||
要点：
|
||||
|
||||
- 如果主持人会末做了口头总结，**以他的总结为骨架**，再用全文信息补全他漏掉的决议。
|
||||
- 每条决议自包含：读这一条就知道改什么、改成什么样，不需要回看正文。
|
||||
|
||||
## 5. 待办事项
|
||||
|
||||
```markdown
|
||||
## <N>、待办事项
|
||||
|
||||
| # | 事项 | 责任人 | 时限/备注 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | <事项> | <人名/角色> | <明确时限，或"持续""长期规则""会后研究"> |
|
||||
```
|
||||
|
||||
要点：
|
||||
|
||||
- **逐条扫一遍全文**收集待办，不止收集结尾总结里的——会议中途随口指派的事项（"到时候喊小朱发一份给你"）最容易丢。
|
||||
- 责任人写转写中能确定的最具体指称（人名 > 角色 > "全体维护人员"）。
|
||||
- 时限没有明说就写性质（"尽快""持续；成果用于推广"），不要编造日期。
|
||||
- 待办按性质排序：一次性交付（带明确期限的在前）→ 规则性/长期事项 → 全员事项。
|
||||
|
||||
---
|
||||
|
||||
## 颗粒度自检
|
||||
|
||||
成文后通读一遍，逐项检查：
|
||||
|
||||
- [ ] 没参会的人能否复述出每条最终决议及其理由？
|
||||
- [ ] 会中被推翻的中间结论，是否已写成"经讨论改为"，而不是被当成最终决议？
|
||||
- [ ] 所有数字、人名、时限是否与转写一致？
|
||||
- [ ] 还能找到一句删掉也不损失信息的话吗？能找到就删。
|
||||
- [ ] 所有"疑似/待确认"标注是否如实保留？
|
||||
150
skills/mermaid-fixer/SKILL.md
Normal file
150
skills/mermaid-fixer/SKILL.md
Normal file
@@ -0,0 +1,150 @@
|
||||
---
|
||||
name: mermaid-fixer
|
||||
description: Fix Mermaid diagram syntax errors in Markdown files. Use when: (1) Mermaid diagrams aren't rendering or show parse errors, (2) User mentions "mermaid syntax error", "mermaid not working", "diagram broken", (3) CI/CD fails on Mermaid validation, (4) Documentation contains Mermaid code blocks that need fixing.
|
||||
---
|
||||
|
||||
# Mermaid Diagram Fixer
|
||||
|
||||
Automatically detects and fixes Mermaid diagram syntax errors in Markdown files using the `check-mermaid.js` validation script.
|
||||
|
||||
## How It Works
|
||||
|
||||
1. **Run `check-mermaid.js`** to get detailed error reports
|
||||
2. **Parse error information** (line numbers, error types, code snippets)
|
||||
3. **Apply intelligent fixes** based on the specific error
|
||||
4. **Verify** by running the check again
|
||||
|
||||
## Core Script
|
||||
|
||||
The `scripts/check-mermaid.js` script is the heart of this skill. It:
|
||||
- Scans Markdown files for ```` ```mermaid ```` code blocks
|
||||
- Validates each block using the Mermaid CLI (`mmdc`)
|
||||
- Returns detailed error reports with line numbers and error messages
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 1: Run the Check Script
|
||||
|
||||
```bash
|
||||
node scripts/check-mermaid.js <path/to/file.md>
|
||||
```
|
||||
|
||||
**Expected output format:**
|
||||
|
||||
- **No errors**: Returns exit code 0 with success message
|
||||
- **Has errors**: Returns exit code 1 with structured error report:
|
||||
|
||||
```markdown
|
||||
## 🚨 Mermaid 语法检查报告
|
||||
|
||||
**检查文件：** `example.md`
|
||||
**检查结果：** ❌ 发现 2 处语法错误 (共检测到 5 个代码块)
|
||||
|
||||
---
|
||||
|
||||
### ❌ 错误 #1 (代码块 #2)
|
||||
|
||||
- **文档位置：** 第 `51` 行至第 `86` 行
|
||||
|
||||
#### 核心错误详情
|
||||
\`\`\`text
|
||||
Error: Parse error on line 13: ...
|
||||
Expecting 'SQE', 'DOUBLECIRCLEEND', ... got 'PS'
|
||||
\`\`\`
|
||||
|
||||
#### 代码内容片段
|
||||
\`\`\`text
|
||||
[shows the problematic code]
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### Step 2: Parse and Understand Errors
|
||||
|
||||
Key information from each error:
|
||||
- **文档位置**: Which line numbers contain the error
|
||||
- **核心错误详情**: The parser error message
|
||||
- **代码内容片段**: The actual Mermaid code causing the issue
|
||||
|
||||
### Step 3: Apply Fixes Based on Error Type
|
||||
|
||||
#### Error Type: "got 'PS'" (Parentheses Issue)
|
||||
|
||||
**Cause**: Parentheses `()` in node labels or arrow labels within subgraphs
|
||||
|
||||
**Fix**: Quote the label
|
||||
```mermaid
|
||||
# Before (causes error)
|
||||
NodeA[Label (with parens)]
|
||||
-->|Label (parens)| NodeB
|
||||
|
||||
# After (fixed)
|
||||
NodeA["Label (with parens)"]
|
||||
-->"|Label (parens)|" NodeB
|
||||
```
|
||||
|
||||
#### Error Type: "got 'SQS'" (Square Brackets Issue)
|
||||
|
||||
**Cause**: Square brackets `[]` in node labels
|
||||
|
||||
**Fix**: Quote the label
|
||||
```mermaid
|
||||
# Before
|
||||
NodeA[Result[]<br/>text]
|
||||
|
||||
# After
|
||||
NodeA["Result[]<br/>text"]
|
||||
```
|
||||
|
||||
#### Error Type: "got 'DIAMOND_START'" or similar
|
||||
|
||||
**Cause**: Curly braces `{}` or other special characters in labels
|
||||
|
||||
**Fix**: Quote the label
|
||||
```mermaid
|
||||
# Before
|
||||
NodeA[Label {variable}]
|
||||
|
||||
# After
|
||||
NodeA["Label {variable}"]
|
||||
```
|
||||
|
||||
### Step 4: Apply the Fix to the File
|
||||
|
||||
1. Read the Markdown file
|
||||
2. Locate the problematic code block using the reported line numbers
|
||||
3. Apply the appropriate fix (quote labels with special characters)
|
||||
4. Save the file
|
||||
|
||||
### Step 5: Verify
|
||||
|
||||
Run `check-mermaid.js` again to confirm all errors are resolved.
|
||||
|
||||
## Common Fix Patterns
|
||||
|
||||
| Error Pattern | Fix Strategy |
|
||||
|---------------|--------------|
|
||||
| `NodeID[label (text)]` | Change to `NodeID["label (text)"]` |
|
||||
| `-->|label (text)|` | Change to `-->|"label (text)"\|` |
|
||||
| `NodeID[label[]text]` | Change to `NodeID["label[]text"]` |
|
||||
| `NodeID[label{text}]` | Change to `NodeID["label{text}"]` |
|
||||
|
||||
## Important Notes
|
||||
|
||||
1. **Always quote labels** containing: `()`, `[]`, `{}`, `<`, `>`, `#`, or Chinese characters
|
||||
2. **Preserve the original structure** - only modify the problematic labels
|
||||
3. **Check all reported errors** - don't stop after fixing just one
|
||||
4. **Re-verify** after each fix round
|
||||
|
||||
## Example Usage
|
||||
|
||||
```
|
||||
User: "My Mermaid diagrams in docs/architecture.md aren't rendering"
|
||||
|
||||
Claude:
|
||||
1. Run: node scripts/check-mermaid.js docs/architecture.md
|
||||
2. Parse error output
|
||||
3. Identify errors (e.g., "got 'PS'" on line 45)
|
||||
4. Read file, locate line 45, find the Mermaid block
|
||||
5. Apply fix: quote labels with parentheses
|
||||
6. Save and verify
|
||||
```
|
||||
23
skills/mermaid-fixer/evals/evals.json
Normal file
23
skills/mermaid-fixer/evals/evals.json
Normal file
@@ -0,0 +1,23 @@
|
||||
{
|
||||
"skill_name": "mermaid-fixer",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "The Mermaid diagrams in demo_scripts/demo.md have syntax errors. Please fix them.",
|
||||
"expected_output": "The skill should run check-mermaid.js, identify the 3 syntax errors, and apply fixes by quoting labels with special characters. After fixes, all 9 Mermaid blocks should pass validation.",
|
||||
"files": ["demo_scripts/demo.md"]
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "My documentation file README.md has broken Mermaid diagrams. Can you check and fix them?",
|
||||
"expected_output": "The skill runs check-mermaid.js on README.md, parses any error reports, applies appropriate fixes based on error types, and verifies the fixes by running the check again.",
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "CI/CD is failing with Mermaid validation errors on docs/api.md. Please fix the diagrams.",
|
||||
"expected_output": "The skill identifies all Mermaid syntax errors using check-mermaid.js, applies fixes for each error type (parentheses, brackets, braces in labels), and ensures the file passes validation.",
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
128
skills/mermaid-fixer/scripts/check-mermaid.js
Normal file
128
skills/mermaid-fixer/scripts/check-mermaid.js
Normal file
@@ -0,0 +1,128 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
const fs = require('fs');
|
||||
const { execSync } = require('child_process');
|
||||
const path = require('path');
|
||||
const os = require('os');
|
||||
|
||||
// 获取命令行传入的 Markdown 文件路径
|
||||
const fileArg = process.argv[2];
|
||||
if (!fileArg) {
|
||||
console.error('❌ 请提供 Markdown 文件路径。用法: node check-mermaid.js <file.md>');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const filePath = path.resolve(fileArg);
|
||||
const fileName = path.basename(filePath);
|
||||
|
||||
if (!fs.existsSync(filePath)) {
|
||||
console.error(`❌ 文件不存在: ${filePath}`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const content = fs.readFileSync(filePath, 'utf-8');
|
||||
|
||||
// 正则匹配 ```mermaid ... ``` 代码块，兼容 Windows(\r\n) 和 Linux(\n)
|
||||
const mermaidRegex = /```mermaid\r?\n([\s\S]*?)```/g;
|
||||
let match;
|
||||
let blockCount = 0;
|
||||
let errorCount = 0;
|
||||
|
||||
// 用于收集所有格式化后的错误报告块
|
||||
const errorReports = [];
|
||||
|
||||
while ((match = mermaidRegex.exec(content)) !== null) {
|
||||
blockCount++;
|
||||
|
||||
const fullMatch = match[0];
|
||||
const code = match[1];
|
||||
|
||||
// 1. 计算在 Markdown 文件中的绝对行号
|
||||
const textBeforeMatch = content.substring(0, match.index);
|
||||
const startLine = textBeforeMatch.split(/\r?\n/).length;
|
||||
const endLine = startLine + fullMatch.split(/\r?\n/).length - 1;
|
||||
|
||||
// 创建临时文件存放单个 Mermaid 代码
|
||||
const tmpFile = path.join(os.tmpdir(), `mermaid-check-${Date.now()}-${blockCount}.mmd`);
|
||||
fs.writeFileSync(tmpFile, code.trim());
|
||||
|
||||
try {
|
||||
// 调用 mmdc 进行静默渲染检查
|
||||
execSync(`npx mmdc -i "${tmpFile}" -o "${tmpFile}.svg" -q`, { stdio: 'pipe' });
|
||||
} catch (error) {
|
||||
errorCount++;
|
||||
|
||||
// 2. 净化报错信息：剔除底层执行堆栈
|
||||
const stderr = error.stderr ? error.stderr.toString() : error.message;
|
||||
const errorLines = stderr.split(/\r?\n/);
|
||||
const cleanErrorLines = [];
|
||||
|
||||
for (const line of errorLines) {
|
||||
if (line.trim().startsWith('at ') ||
|
||||
line.includes('Parser3.parseError') ||
|
||||
line.includes('fromText')) {
|
||||
break;
|
||||
}
|
||||
cleanErrorLines.push(line);
|
||||
}
|
||||
const cleanErrorOutput = cleanErrorLines.join('\n').trim();
|
||||
|
||||
// 3. 截断代码内容：最少3行，最多6行
|
||||
const codeLines = code.split(/\r?\n/).filter(l => l.trim() !== '');
|
||||
let displayCode = '';
|
||||
|
||||
if (codeLines.length <= 6) {
|
||||
displayCode = codeLines.join('\n');
|
||||
} else {
|
||||
const head = codeLines.slice(0, 3).join('\n');
|
||||
const tail = codeLines.slice(-3).join('\n');
|
||||
displayCode = `${head}\n ...\n ... (中间省略 ${codeLines.length - 6} 行) ...\n ...\n${tail}`;
|
||||
}
|
||||
|
||||
// 4. 组装单个错误的 Markdown 块
|
||||
errorReports.push(`### ❌ 错误 #${errorCount} (代码块 #${blockCount})
|
||||
|
||||
- **文档位置：** 第 \`${startLine}\` 行至第 \`${endLine}\` 行
|
||||
|
||||
#### 核心错误详情
|
||||
\`\`\`text
|
||||
${cleanErrorOutput}
|
||||
\`\`\`
|
||||
|
||||
#### 代码内容片段
|
||||
\`\`\`text
|
||||
${displayCode}
|
||||
\`\`\``);
|
||||
|
||||
} finally {
|
||||
// 清理临时文件
|
||||
if (fs.existsSync(tmpFile)) fs.unlinkSync(tmpFile);
|
||||
if (fs.existsSync(`${tmpFile}.svg`)) fs.unlinkSync(`${tmpFile}.svg`);
|
||||
}
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------------
|
||||
// 生成最终的 Markdown 报告输出
|
||||
// ------------------------------------------------------------------
|
||||
|
||||
if (errorCount > 0) {
|
||||
// 存在错误的情况
|
||||
console.log(`## 🚨 Mermaid 语法检查报告\n`);
|
||||
console.log(`**检查文件：** \`${fileName}\``);
|
||||
console.log(`**检查结果：** ❌ 发现 ${errorCount} 处语法错误 (共检测到 ${blockCount} 个代码块)\n`);
|
||||
console.log(`---\n`);
|
||||
console.log(errorReports.join('\n\n---\n\n'));
|
||||
|
||||
// 返回非零状态码，确保在 CI/CD 或 Git Hook 中能够阻断流程
|
||||
process.exit(1);
|
||||
} else {
|
||||
// 全部正确或没有代码块的情况
|
||||
console.log(`## 🎉 Mermaid 语法检查报告\n`);
|
||||
console.log(`**检查文件：** \`${fileName}\``);
|
||||
if (blockCount === 0) {
|
||||
console.log(`**检查结果：** ⚠️ 未检测到 Mermaid 代码块`);
|
||||
} else {
|
||||
console.log(`**检查结果：** ✅ 全部通过 (共检测到 ${blockCount} 个代码块)`);
|
||||
}
|
||||
process.exit(0);
|
||||
}
|
||||
212
skills/obsidian-cli/SKILL.md
Normal file
212
skills/obsidian-cli/SKILL.md
Normal file
@@ -0,0 +1,212 @@
|
||||
---
|
||||
name: obsidian-cli
|
||||
description: >-
|
||||
Obsidian CLI skill for reading, creating, editing, searching, and managing note content
|
||||
in Obsidian vaults from the command line. Supports daily notes, tasks, properties, tags,
|
||||
links, file history, templates, and full file CRUD operations.
|
||||
Use this skill whenever the user wants to read or edit Obsidian notes, search vault content,
|
||||
manage tasks or properties, append/prepend content, or perform any vault note operation.
|
||||
Also triggers when the user mentions "obsidian cli", "obsidian command", "vault" operations,
|
||||
or "obsidian" in a terminal/CLI context. Always invoke this skill before attempting
|
||||
Obsidian-related operations to ensure correct command syntax and available parameters.
|
||||
Requires Obsidian 1.12+ with CLI enabled and the Obsidian app running.
|
||||
---
|
||||
|
||||
# Obsidian CLI
|
||||
|
||||
Control Obsidian from the command line. The Obsidian desktop app must be running — the CLI connects to it over a local bridge.
|
||||
|
||||
> **Prerequisites:** Obsidian installer 1.12.7+ with CLI enabled (Settings -> General -> Command line interface).
|
||||
|
||||
## Syntax
|
||||
|
||||
**Parameters** use `key=value`. Quote values containing spaces:
|
||||
|
||||
```bash
|
||||
obsidian create name="My Note" content="Hello world"
|
||||
```
|
||||
|
||||
**Flags** are boolean switches with no value:
|
||||
|
||||
```bash
|
||||
obsidian create name="My Note" open overwrite
|
||||
```
|
||||
|
||||
**Multiline content:** Use `\n` for newline, `\t` for tab.
|
||||
|
||||
**Copy output:** Append `--copy` to any command to copy the result to clipboard.
|
||||
|
||||
## Targeting
|
||||
|
||||
### File targeting
|
||||
|
||||
Most file commands accept `file` and/or `path`. If neither is given, the active file is used.
|
||||
|
||||
| Parameter | Behavior |
|
||||
|-----------|----------|
|
||||
| `file=<name>` | Resolves like a wikilink — name only, no path or extension needed |
|
||||
| `path=<path>` | Exact vault-relative path, e.g. `folder/note.md` |
|
||||
|
||||
### Vault targeting
|
||||
|
||||
If your terminal CWD is a vault folder, that vault is used. Otherwise the active vault is used. Override with `vault=<name>` or `vault=<id>` as the first parameter:
|
||||
|
||||
```bash
|
||||
obsidian vault=Notes daily
|
||||
obsidian vault="My Vault" search query="test"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Commands
|
||||
|
||||
For the full parameter reference of every command, read `references/commands-reference.md`.
|
||||
|
||||
### Daily notes
|
||||
|
||||
```bash
|
||||
obsidian daily # Open today's daily note
|
||||
obsidian daily:read # Read daily note content
|
||||
obsidian daily:append content="- [ ] Buy groceries" # Append to daily note
|
||||
obsidian daily:prepend content="# Summary" # Prepend to daily note
|
||||
obsidian daily:path # Get daily note file path
|
||||
```
|
||||
|
||||
### Files and folders
|
||||
|
||||
```bash
|
||||
obsidian file file=Recipe # Show file info
|
||||
obsidian files folder="Projects" ext=md # List files (filter by folder/extension)
|
||||
obsidian folders # List all folders
|
||||
obsidian open file=Recipe # Open a file
|
||||
obsidian read file=Recipe # Read file contents
|
||||
obsidian create name="New Note" content="# Hello" # Create a note
|
||||
obsidian create name="Trip" template=Travel open # Create from template and open
|
||||
obsidian append file=Recipe content="New line" # Append to file
|
||||
obsidian prepend file=Recipe content="Header text" # Prepend after frontmatter
|
||||
obsidian move file=Recipe to="Archive/Recipe.md" # Move/rename file
|
||||
obsidian rename file=Recipe name="New Recipe" # Rename file
|
||||
obsidian delete file=Recipe # Delete file (to trash)
|
||||
obsidian delete file=Recipe permanent # Delete permanently
|
||||
```
|
||||
|
||||
### Search
|
||||
|
||||
```bash
|
||||
obsidian search query="meeting notes" # Search vault (returns file paths)
|
||||
obsidian search query="TODO" path="Projects" limit=10 # Search within a folder
|
||||
obsidian search:context query="error" # Search with line context (grep-style)
|
||||
obsidian search:open query="initial query" # Open search in Obsidian UI
|
||||
```
|
||||
|
||||
### Tasks
|
||||
|
||||
```bash
|
||||
obsidian tasks # List all tasks
|
||||
obsidian tasks todo # Incomplete tasks only
|
||||
obsidian tasks daily # Tasks from today's daily note
|
||||
obsidian tasks file=Recipe done verbose # Completed tasks from a file, with line numbers
|
||||
obsidian tasks daily total # Count tasks in daily note
|
||||
obsidian task ref="Recipe.md:8" toggle # Toggle task completion
|
||||
obsidian task daily line=3 done # Mark daily note task as done
|
||||
obsidian task file=Recipe line=8 status=- # Set custom status character
|
||||
```
|
||||
|
||||
### Properties
|
||||
|
||||
```bash
|
||||
obsidian properties # List all properties in vault
|
||||
obsidian properties active # Properties of active file
|
||||
obsidian properties name=status counts # Count occurrences of a property
|
||||
obsidian property:set name=status value=done file=Recipe # Set a property
|
||||
obsidian property:read name=status file=Recipe # Read a property value
|
||||
obsidian property:remove name=draft file=Recipe # Remove a property
|
||||
obsidian aliases file=Recipe # List aliases for a file
|
||||
```
|
||||
|
||||
### Tags
|
||||
|
||||
```bash
|
||||
obsidian tags # List all tags
|
||||
obsidian tags sort=count counts # Tags sorted by frequency with counts
|
||||
obsidian tags active # Tags of active file
|
||||
obsidian tag name=project verbose # Tag info with file list
|
||||
```
|
||||
|
||||
### Links
|
||||
|
||||
```bash
|
||||
obsidian backlinks file=Recipe # List backlinks to a file
|
||||
obsidian backlinks file=Recipe counts # With link counts
|
||||
obsidian links file=Recipe # Outgoing links from a file
|
||||
obsidian unresolved # List unresolved links
|
||||
obsidian orphans # Files with no incoming links
|
||||
obsidian deadends # Files with no outgoing links
|
||||
```
|
||||
|
||||
### Outline
|
||||
|
||||
```bash
|
||||
obsidian outline file=Recipe # Show headings (tree format)
|
||||
obsidian outline file=Recipe format=json total # JSON format with heading count
|
||||
```
|
||||
|
||||
### File history
|
||||
|
||||
```bash
|
||||
obsidian diff # List versions of active file
|
||||
obsidian diff file=Recipe from=1 # Compare latest version to current
|
||||
obsidian diff file=Recipe from=3 to=1 # Compare two versions
|
||||
obsidian history file=Recipe # Local history versions
|
||||
obsidian history:read file=Recipe version=2 # Read a history version
|
||||
obsidian history:restore file=Recipe version=3 # Restore a history version
|
||||
```
|
||||
|
||||
### Templates
|
||||
|
||||
```bash
|
||||
obsidian templates # List templates
|
||||
obsidian template:read name=Meeting resolve # Read template with variables resolved
|
||||
obsidian template:insert name=Meeting # Insert template into active file
|
||||
```
|
||||
|
||||
### Vault info
|
||||
|
||||
```bash
|
||||
obsidian vault # Show vault info
|
||||
obsidian vault info=files # File count only
|
||||
obsidian vaults verbose # List all known vaults with paths
|
||||
obsidian wordcount file=Recipe # Word and character count
|
||||
obsidian wordcount words # Word count only
|
||||
```
|
||||
|
||||
### General
|
||||
|
||||
```bash
|
||||
obsidian help # List all commands
|
||||
obsidian version # Show Obsidian version
|
||||
obsidian reload # Reload app window
|
||||
obsidian restart # Restart app
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting: CLI Connection Issues
|
||||
|
||||
When `obsidian` commands return empty output (with exit code 0) or are unresponsive, the CLI bridge connection is likely broken. Follow this procedure:
|
||||
|
||||
1. **Detect the issue**: If a command produces empty output with exit code 0, the bridge connection is broken
|
||||
2. **Ask the user**: Use AskUserQuestion to ask the user whether they allow running `obsidian reload` to reload the Obsidian window and restore the connection
|
||||
3. **If the user agrees**: Run `obsidian reload`, wait about 3 seconds, then retry the original command
|
||||
4. **If the user declines**: Fall back to reading/writing vault files directly via the filesystem (locate the vault path from `%APPDATA%/obsidian/obsidian.json`, then use Read/Edit/Write tools to operate on .md files directly)
|
||||
|
||||
> **Note**: `obsidian reload` reloads the Obsidian window. It does not affect unsaved data, but will briefly interrupt the current editing state.
|
||||
|
||||
---
|
||||
|
||||
## Tips
|
||||
|
||||
- **Clipboard:** Add `--copy` to any command to copy output.
|
||||
- **Counts:** Add `total` to list commands to get a count instead of full output.
|
||||
- **Output formats:** Many list commands accept `format=json|tsv|csv` for structured output.
|
||||
- **Help:** Run `obsidian help` for an always-up-to-date command list. Run `obsidian help <command>` for command-specific help.
|
||||
568
skills/obsidian-cli/references/commands-reference.md
Normal file
568
skills/obsidian-cli/references/commands-reference.md
Normal file
@@ -0,0 +1,568 @@
|
||||
# Commands Reference
|
||||
|
||||
Full parameter reference for Obsidian CLI note content commands. Required parameters are marked `(required)`.
|
||||
|
||||
## Table of contents
|
||||
|
||||
- [General](#general)
|
||||
- [Daily notes](#daily-notes)
|
||||
- [Files and folders](#files-and-folders)
|
||||
- [Search](#search)
|
||||
- [Tasks](#tasks)
|
||||
- [Properties](#properties)
|
||||
- [Tags](#tags)
|
||||
- [Links](#links)
|
||||
- [Outline](#outline)
|
||||
- [File history](#file-history)
|
||||
- [Templates](#templates)
|
||||
- [Vault](#vault)
|
||||
- [Wordcount](#wordcount)
|
||||
|
||||
---
|
||||
|
||||
## General
|
||||
|
||||
### `help`
|
||||
|
||||
Show available commands or help for a specific command.
|
||||
|
||||
| Parameter | Description |
|
||||
| ----------- | --------------------------------- |
|
||||
| `<command>` | Show help for a specific command. |
|
||||
|
||||
### `version`
|
||||
|
||||
Show Obsidian version.
|
||||
|
||||
### `reload`
|
||||
|
||||
Reload the app window.
|
||||
|
||||
### `restart`
|
||||
|
||||
Restart the app.
|
||||
|
||||
---
|
||||
|
||||
## Daily notes
|
||||
|
||||
### `daily`
|
||||
|
||||
Open daily note.
|
||||
|
||||
| Parameter | Description |
|
||||
| ------------------------------- | ---------------------- |
|
||||
| `paneType=tab\|split\|window` | Pane type to open in |
|
||||
|
||||
### `daily:path`
|
||||
|
||||
Get daily note path. Returns the expected path even if the file hasn't been created yet.
|
||||
|
||||
### `daily:read`
|
||||
|
||||
Read daily note contents.
|
||||
|
||||
### `daily:append`
|
||||
|
||||
Append content to daily note.
|
||||
|
||||
| Parameter | Description |
|
||||
| ------------------------------- | ---------------------------- |
|
||||
| `content=<text>` | (required) Content to append |
|
||||
| `paneType=tab\|split\|window` | Pane type to open in |
|
||||
| `inline` | Append without newline |
|
||||
| `open` | Open file after adding |
|
||||
|
||||
### `daily:prepend`
|
||||
|
||||
Prepend content to daily note.
|
||||
|
||||
| Parameter | Description |
|
||||
| ------------------------------- | ---------------------------- |
|
||||
| `content=<text>` | (required) Content to prepend|
|
||||
| `paneType=tab\|split\|window` | Pane type to open in |
|
||||
| `inline` | Prepend without newline |
|
||||
| `open` | Open file after adding |
|
||||
|
||||
---
|
||||
|
||||
## Files and folders
|
||||
|
||||
### `file`
|
||||
|
||||
Show file info (default: active file). Returns path, name, extension, size, created/modified timestamps.
|
||||
|
||||
| Parameter | Description |
|
||||
| ------------- | ----------- |
|
||||
| `file=<name>` | File name |
|
||||
| `path=<path>` | File path |
|
||||
|
||||
### `files`
|
||||
|
||||
List files in the vault.
|
||||
|
||||
| Parameter | Description |
|
||||
| ----------------- | ------------------------ |
|
||||
| `folder=<path>` | Filter by folder |
|
||||
| `ext=<extension>` | Filter by extension |
|
||||
| `total` | Return file count |
|
||||
|
||||
### `folder`
|
||||
|
||||
Show folder info.
|
||||
|
||||
| Parameter | Description |
|
||||
| ------------------------------ | -------------------------- |
|
||||
| `path=<path>` | (required) Folder path |
|
||||
| `info=files\|folders\|size` | Return specific info only |
|
||||
|
||||
### `folders`
|
||||
|
||||
List folders in the vault.
|
||||
|
||||
| Parameter | Description |
|
||||
| --------------- | ------------------------ |
|
||||
| `folder=<path>` | Filter by parent folder |
|
||||
| `total` | Return folder count |
|
||||
|
||||
### `open`
|
||||
|
||||
Open a file.
|
||||
|
||||
| Parameter | Description |
|
||||
| ------------- | ---------------- |
|
||||
| `file=<name>` | File name |
|
||||
| `path=<path>` | File path |
|
||||
| `newtab` | Open in new tab |
|
||||
|
||||
### `create`
|
||||
|
||||
Create or overwrite a file.
|
||||
|
||||
| Parameter | Description |
|
||||
| ------------------ | ------------------------ |
|
||||
| `name=<name>` | File name |
|
||||
| `path=<path>` | File path |
|
||||
| `content=<text>` | Initial content |
|
||||
| `template=<name>` | Template to use |
|
||||
| `overwrite` | Overwrite if exists |
|
||||
| `open` | Open after creating |
|
||||
| `newtab` | Open in new tab |
|
||||
|
||||
### `read`
|
||||
|
||||
Read file contents (default: active file).
|
||||
|
||||
| Parameter | Description |
|
||||
| ------------- | ----------- |
|
||||
| `file=<name>` | File name |
|
||||
| `path=<path>` | File path |
|
||||
|
||||
### `append`
|
||||
|
||||
Append content to a file (default: active file).
|
||||
|
||||
| Parameter | Description |
|
||||
| ---------------- | ---------------------------- |
|
||||
| `file=<name>` | File name |
|
||||
| `path=<path>` | File path |
|
||||
| `content=<text>` | (required) Content to append |
|
||||
| `inline` | Append without newline |
|
||||
|
||||
### `prepend`
|
||||
|
||||
Prepend content after frontmatter (default: active file).
|
||||
|
||||
| Parameter | Description |
|
||||
| ---------------- | ----------------------------- |
|
||||
| `file=<name>` | File name |
|
||||
| `path=<path>` | File path |
|
||||
| `content=<text>` | (required) Content to prepend |
|
||||
| `inline` | Prepend without newline |
|
||||
|
||||
### `move`
|
||||
|
||||
Move or rename a file (default: active file). Auto-updates internal links if enabled.
|
||||
|
||||
| Parameter | Description |
|
||||
| -------------- | ----------------------------- |
|
||||
| `file=<name>` | File name |
|
||||
| `path=<path>` | File path |
|
||||
| `to=<path>` | (required) Destination path |
|
||||
|
||||
### `rename`
|
||||
|
||||
Rename a file (default: active file). Extension preserved if omitted. Use `move` to rename and move simultaneously.
|
||||
|
||||
| Parameter | Description |
|
||||
| -------------- | ------------------------- |
|
||||
| `file=<name>` | File name |
|
||||
| `path=<path>` | File path |
|
||||
| `name=<name>` | (required) New file name |
|
||||
|
||||
### `delete`
|
||||
|
||||
Delete a file (default: active file, trash by default).
|
||||
|
||||
| Parameter | Description |
|
||||
| -------------- | ------------------------------ |
|
||||
| `file=<name>` | File name |
|
||||
| `path=<path>` | File path |
|
||||
| `permanent` | Skip trash, delete permanently |
|
||||
|
||||
---
|
||||
|
||||
## Search
|
||||
|
||||
### `search`
|
||||
|
||||
Search vault for text. Returns matching file paths.
|
||||
|
||||
| Parameter | Description |
|
||||
| -------------------- | ------------------------------ |
|
||||
| `query=<text>` | (required) Search query |
|
||||
| `path=<folder>` | Limit to folder |
|
||||
| `limit=<n>` | Max files |
|
||||
| `format=text\|json` | Output format (default: text) |
|
||||
| `total` | Return match count |
|
||||
| `case` | Case sensitive |
|
||||
|
||||
### `search:context`
|
||||
|
||||
Search with matching line context. Returns grep-style `path:line: text` output.
|
||||
|
||||
| Parameter | Description |
|
||||
| -------------------- | ------------------------------ |
|
||||
| `query=<text>` | (required) Search query |
|
||||
| `path=<folder>` | Limit to folder |
|
||||
| `limit=<n>` | Max files |
|
||||
| `format=text\|json` | Output format (default: text) |
|
||||
| `case` | Case sensitive |
|
||||
|
||||
### `search:open`
|
||||
|
||||
Open search view in Obsidian.
|
||||
|
||||
| Parameter | Description |
|
||||
| --------------- | ---------------------- |
|
||||
| `query=<text>` | Initial search query |
|
||||
|
||||
---
|
||||
|
||||
## Tasks
|
||||
|
||||
### `tasks`
|
||||
|
||||
List tasks in the vault.
|
||||
|
||||
| Parameter | Description |
|
||||
| ------------------------ | --------------------------------- |
|
||||
| `file=<name>` | Filter by file name |
|
||||
| `path=<path>` | Filter by file path |
|
||||
| `status="<char>"` | Filter by status character |
|
||||
| `total` | Return task count |
|
||||
| `done` | Show completed tasks |
|
||||
| `todo` | Show incomplete tasks |
|
||||
| `verbose` | Group by file with line numbers |
|
||||
| `format=json\|tsv\|csv` | Output format (default: text) |
|
||||
| `active` | Show tasks for active file |
|
||||
| `daily` | Show tasks from daily note |
|
||||
|
||||
### `task`
|
||||
|
||||
Show or update a task.
|
||||
|
||||
| Parameter | Description |
|
||||
| -------------------- | -------------------------- |
|
||||
| `ref=<path:line>` | Task reference (path:line) |
|
||||
| `file=<name>` | File name |
|
||||
| `path=<path>` | File path |
|
||||
| `line=<n>` | Line number |
|
||||
| `status="<char>"` | Set status character |
|
||||
| `toggle` | Toggle task status |
|
||||
| `daily` | Target daily note |
|
||||
| `done` | Mark as done |
|
||||
| `todo` | Mark as todo |
|
||||
|
||||
---
|
||||
|
||||
## Properties
|
||||
|
||||
### `aliases`
|
||||
|
||||
List aliases in the vault.
|
||||
|
||||
| Parameter | Description |
|
||||
| ------------- | -------------------- |
|
||||
| `file=<name>` | File name |
|
||||
| `path=<path>` | File path |
|
||||
| `total` | Return alias count |
|
||||
| `verbose` | Include file paths |
|
||||
| `active` | Show for active file |
|
||||
|
||||
### `properties`
|
||||
|
||||
List properties in the vault.
|
||||
|
||||
| Parameter | Description |
|
||||
| ------------------------ | ----------------------------- |
|
||||
| `file=<name>` | Show properties for file |
|
||||
| `path=<path>` | Show properties for path |
|
||||
| `name=<name>` | Get specific property count |
|
||||
| `sort=count` | Sort by count (default: name) |
|
||||
| `format=yaml\|json\|tsv` | Output format (default: yaml) |
|
||||
| `total` | Return property count |
|
||||
| `counts` | Include occurrence counts |
|
||||
| `active` | Show for active file |
|
||||
|
||||
### `property:set`
|
||||
|
||||
Set a property on a file (default: active file).
|
||||
|
||||
| Parameter | Description |
|
||||
| ---------------------------------------------------- | -------------------- |
|
||||
| `name=<name>` | (required) Property name |
|
||||
| `value=<value>` | (required) Property value |
|
||||
| `type=text\|list\|number\|checkbox\|date\|datetime` | Property type |
|
||||
| `file=<name>` | File name |
|
||||
| `path=<path>` | File path |
|
||||
|
||||
### `property:remove`
|
||||
|
||||
Remove a property from a file (default: active file).
|
||||
|
||||
| Parameter | Description |
|
||||
| ------------- | ------------------------ |
|
||||
| `name=<name>` | (required) Property name |
|
||||
| `file=<name>` | File name |
|
||||
| `path=<path>` | File path |
|
||||
|
||||
### `property:read`
|
||||
|
||||
Read a property value from a file (default: active file).
|
||||
|
||||
| Parameter | Description |
|
||||
| ------------- | ------------------------ |
|
||||
| `name=<name>` | (required) Property name |
|
||||
| `file=<name>` | File name |
|
||||
| `path=<path>` | File path |
|
||||
|
||||
---
|
||||
|
||||
## Tags
|
||||
|
||||
### `tags`
|
||||
|
||||
List tags in the vault.
|
||||
|
||||
| Parameter | Description |
|
||||
| ------------------------ | ----------------------------- |
|
||||
| `file=<name>` | File name |
|
||||
| `path=<path>` | File path |
|
||||
| `sort=count` | Sort by count (default: name) |
|
||||
| `total` | Return tag count |
|
||||
| `counts` | Include tag counts |
|
||||
| `format=json\|tsv\|csv` | Output format (default: tsv) |
|
||||
| `active` | Show for active file |
|
||||
|
||||
### `tag`
|
||||
|
||||
Get tag info.
|
||||
|
||||
| Parameter | Description |
|
||||
| ------------ | --------------------------- |
|
||||
| `name=<tag>` | (required) Tag name |
|
||||
| `total` | Return occurrence count |
|
||||
| `verbose` | Include file list and count |
|
||||
|
||||
---
|
||||
|
||||
## Links
|
||||
|
||||
### `backlinks`
|
||||
|
||||
List backlinks to a file (default: active file).
|
||||
|
||||
| Parameter | Description |
|
||||
| ------------------------ | ----------------------------- |
|
||||
| `file=<name>` | Target file name |
|
||||
| `path=<path>` | Target file path |
|
||||
| `counts` | Include link counts |
|
||||
| `total` | Return backlink count |
|
||||
| `format=json\|tsv\|csv` | Output format (default: tsv) |
|
||||
|
||||
### `links`
|
||||
|
||||
List outgoing links from a file (default: active file).
|
||||
|
||||
| Parameter | Description |
|
||||
| ------------- | ------------------ |
|
||||
| `file=<name>` | File name |
|
||||
| `path=<path>` | File path |
|
||||
| `total` | Return link count |
|
||||
|
||||
### `unresolved`
|
||||
|
||||
List unresolved links in vault.
|
||||
|
||||
| Parameter | Description |
|
||||
| ------------------------ | ----------------------------- |
|
||||
| `total` | Return unresolved link count |
|
||||
| `counts` | Include link counts |
|
||||
| `verbose` | Include source files |
|
||||
| `format=json\|tsv\|csv` | Output format (default: tsv) |
|
||||
|
||||
### `orphans`
|
||||
|
||||
List files with no incoming links.
|
||||
|
||||
| Parameter | Description |
|
||||
| --------- | ------------------- |
|
||||
| `total` | Return orphan count |
|
||||
|
||||
### `deadends`
|
||||
|
||||
List files with no outgoing links.
|
||||
|
||||
| Parameter | Description |
|
||||
| --------- | ---------------------- |
|
||||
| `total` | Return dead-end count |
|
||||
|
||||
---
|
||||
|
||||
## Outline
|
||||
|
||||
### `outline`
|
||||
|
||||
Show headings for a file.
|
||||
|
||||
| Parameter | Description |
|
||||
| ------------------------ | ------------------------------- |
|
||||
| `file=<name>` | File name |
|
||||
| `path=<path>` | File path |
|
||||
| `format=tree\|md\|json` | Output format (default: tree) |
|
||||
| `total` | Return heading count |
|
||||
|
||||
---
|
||||
|
||||
## File history
|
||||
|
||||
### `diff`
|
||||
|
||||
List or compare versions from local File recovery and Sync. Versions numbered newest to oldest.
|
||||
|
||||
| Parameter | Description |
|
||||
| ---------------------- | ------------------------------ |
|
||||
| `file=<name>` | File name |
|
||||
| `path=<path>` | File path |
|
||||
| `from=<n>` | Version number to diff from |
|
||||
| `to=<n>` | Version number to diff to |
|
||||
| `filter=local\|sync` | Filter by version source |
|
||||
|
||||
### `history`
|
||||
|
||||
List versions from File recovery only.
|
||||
|
||||
| Parameter | Description |
|
||||
| ------------- | ----------- |
|
||||
| `file=<name>` | File name |
|
||||
| `path=<path>` | File path |
|
||||
|
||||
### `history:list`
|
||||
|
||||
List all files with local history.
|
||||
|
||||
### `history:read`
|
||||
|
||||
Read a local history version.
|
||||
|
||||
| Parameter | Description |
|
||||
| --------------- | ------------------------------ |
|
||||
| `file=<name>` | File name |
|
||||
| `path=<path>` | File path |
|
||||
| `version=<n>` | Version number (default: 1) |
|
||||
|
||||
### `history:restore`
|
||||
|
||||
Restore a local history version.
|
||||
|
||||
| Parameter | Description |
|
||||
| --------------- | ------------------------ |
|
||||
| `file=<name>` | File name |
|
||||
| `path=<path>` | File path |
|
||||
| `version=<n>` | (required) Version number|
|
||||
|
||||
### `history:open`
|
||||
|
||||
Open file recovery.
|
||||
|
||||
| Parameter | Description |
|
||||
| ------------- | ----------- |
|
||||
| `file=<name>` | File name |
|
||||
| `path=<path>` | File path |
|
||||
|
||||
---
|
||||
|
||||
## Templates
|
||||
|
||||
### `templates`
|
||||
|
||||
List templates.
|
||||
|
||||
| Parameter | Description |
|
||||
| --------- | ---------------------- |
|
||||
| `total` | Return template count |
|
||||
|
||||
### `template:read`
|
||||
|
||||
Read template content.
|
||||
|
||||
| Parameter | Description |
|
||||
| ------------------ | --------------------------------------------------- |
|
||||
| `name=<template>` | (required) Template name |
|
||||
| `title=<title>` | Title for variable resolution |
|
||||
| `resolve` | Resolve `{{date}}`, `{{time}}`, `{{title}}` variables |
|
||||
|
||||
### `template:insert`
|
||||
|
||||
Insert template into active file.
|
||||
|
||||
| Parameter | Description |
|
||||
| ------------------ | ------------------------ |
|
||||
| `name=<template>` | (required) Template name |
|
||||
|
||||
---
|
||||
|
||||
## Vault
|
||||
|
||||
### `vault`
|
||||
|
||||
Show vault info.
|
||||
|
||||
| Parameter | Description |
|
||||
| ---------------------------------------- | -------------------------- |
|
||||
| `info=name\|path\|files\|folders\|size` | Return specific info only |
|
||||
|
||||
### `vaults`
|
||||
|
||||
List known vaults.
|
||||
|
||||
| Parameter | Description |
|
||||
| ---------- | -------------------- |
|
||||
| `total` | Return vault count |
|
||||
| `verbose` | Include vault paths |
|
||||
|
||||
---
|
||||
|
||||
## Wordcount
|
||||
|
||||
### `wordcount`
|
||||
|
||||
Count words and characters.
|
||||
|
||||
| Parameter | Description |
|
||||
| --------------- | ---------------------------- |
|
||||
| `file=<name>` | File name |
|
||||
| `path=<path>` | File path |
|
||||
| `words` | Return word count only |
|
||||
| `characters` | Return character count only |
|
||||
201
skills/seq-api/SKILL.md
Normal file
201
skills/seq-api/SKILL.md
Normal file
@@ -0,0 +1,201 @@
|
||||
---
|
||||
name: seq-api
|
||||
description: Guide for making HTTP API calls to the Seq structured log server (by Datalust). Use this skill whenever the user wants to interact with Seq programmatically — including ingesting events/logs/traces, querying events, managing API keys, signals, dashboards, alerts, users, workspaces, retention policies, app instances, backups, diagnostics, or any other Seq server resource. Also trigger when the user mentions Seq API, CLEF ingestion, Seq health checks, Seq SQL queries via API, or building scripts/automation that talk to a Seq server. Even if the user just says "send logs to Seq" or "query Seq" or "check Seq health", use this skill.
|
||||
---
|
||||
|
||||
# Seq HTTP API Skill
|
||||
|
||||
This skill provides guidance for calling the Seq server HTTP API. Seq is a centralized structured log server by Datalust. Its full API is REST-like, JSON-based, and navigable from the `/api/` root resource.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Base URL & Discovery
|
||||
|
||||
The API root is at `{SEQ_SERVER_URL}/api/`. A GET to this endpoint returns a JSON object listing links to all resource groups (e.g., `ApiKeysResources`, `EventsResources`).
|
||||
|
||||
### Authentication
|
||||
|
||||
Two methods (only needed when auth is enabled on the server):
|
||||
|
||||
1. **Query string**: `?apiKey={YOUR_API_KEY}`
|
||||
2. **Header**: `X-Seq-ApiKey: {YOUR_API_KEY}`
|
||||
|
||||
API keys are the recommended method. Each key has specific permissions — make sure the key has the required permission level for the endpoint you're calling (see permission levels below).
|
||||
|
||||
### Permission Levels
|
||||
|
||||
Seq endpoints require one of these permission levels (from lowest to highest):
|
||||
|
||||
- **Public** — No auth needed (health checks, resource listings, auth settings)
|
||||
- **Ingest** — Required for writing events when `RequireApiKeyForWritingEvents` is enabled
|
||||
- **Read** — View events, signals, dashboards, alerts, queries
|
||||
- **Write** — Create/update/delete signals, dashboards, alerts, queries
|
||||
- **Project** — Administrative project-level access (retention policies, indexes, alert state, diagnostics metrics)
|
||||
- **Organization** — Manage users
|
||||
- **System** — Full server administration (apps, backups, cluster, feeds, settings, licenses)
|
||||
|
||||
### Common Patterns
|
||||
|
||||
All resource endpoints follow a consistent pattern:
|
||||
|
||||
| Operation | Method | Path |
|
||||
|-----------|--------|------|
|
||||
| List all | GET | `api/{resource}` |
|
||||
| Create | POST | `api/{resource}` |
|
||||
| Get one | GET | `api/{resource}/{id}` |
|
||||
| Update | PUT | `api/{resource}/{id}` |
|
||||
| Delete | DELETE | `api/{resource}/{id}` |
|
||||
| Get template | GET | `api/{resource}/template` |
|
||||
| Resource links | GET | `api/{resource}/resources` |
|
||||
|
||||
Use the `template` endpoint to get a blank object with the correct structure before creating a new resource.
|
||||
|
||||
### Content Type
|
||||
|
||||
All API requests and responses use `application/json`, except:
|
||||
- CLEF ingestion uses `application/vnd.serilog.clef`
|
||||
- OpenTelemetry ingestion uses protocol-specific content types
|
||||
|
||||
---
|
||||
|
||||
## Key Tasks
|
||||
|
||||
### 1. Health Check
|
||||
|
||||
```
|
||||
GET {SEQ_URL}/health
|
||||
```
|
||||
|
||||
Returns 200 (healthy) or 503 (unhealthy) with JSON body `{"status": "..."}`. No authentication needed. For clusters, use `/health/cluster`.
|
||||
|
||||
### 2. Ingest Events (CLEF Format)
|
||||
|
||||
**Read `references/ingestion.md` for full CLEF format details and all reified properties.**
|
||||
|
||||
```
|
||||
POST {SEQ_URL}/ingest/clef
|
||||
Content-Type: application/vnd.serilog.clef
|
||||
X-Seq-ApiKey: {API_KEY}
|
||||
|
||||
{"@t":"2024-01-15T10:30:00Z","@mt":"User {User} logged in","User":"alice","@l":"Information"}
|
||||
{"@t":"2024-01-15T10:30:01Z","@mt":"Error processing {OrderId}","OrderId":123,"@l":"Error","@x":"System.Exception: ..."}
|
||||
```
|
||||
|
||||
Response: `201 Created` with `{"MinimumLevelAccepted": null}` on success.
|
||||
|
||||
### 3. Ingest via OpenTelemetry
|
||||
|
||||
```
|
||||
POST {SEQ_URL}/ingest/otlp/v1/logs
|
||||
POST {SEQ_URL}/ingest/otlp/v1/traces
|
||||
POST {SEQ_URL}/ingest/otlp/v1/metrics
|
||||
```
|
||||
|
||||
### 4. Query Events
|
||||
|
||||
```
|
||||
GET {SEQ_URL}/api/events?count=30&filter=StatusCode%20%3E%20399
|
||||
```
|
||||
|
||||
Key query parameters: `count`, `filter` (Seq filter expression), `signal` (signal ID), `fromDateUtc`, `toDateUtc`.
|
||||
|
||||
For SQL-style queries:
|
||||
|
||||
```
|
||||
POST {SEQ_URL}/api/data
|
||||
Content-Type: application/json
|
||||
X-Seq-ApiKey: {API_KEY}
|
||||
|
||||
{
|
||||
"Query": "select count(*) from stream group by RequestPath",
|
||||
"RangeStartUtc": "2024-01-01T00:00:00Z",
|
||||
"RangeEndUtc": "2024-01-02T00:00:00Z",
|
||||
"SignalExpression": null
|
||||
}
|
||||
```
|
||||
|
||||
Also available via GET: `GET /api/data?q={query}&rangeStartUtc=...&rangeEndUtc=...`
|
||||
|
||||
### 5. Manage API Keys
|
||||
|
||||
```bash
|
||||
# List keys (need Read or Project permission)
|
||||
GET /api/apikeys
|
||||
|
||||
# Create a key
|
||||
POST /api/apikeys
|
||||
{"Title": "My App Key", "AssignedPermissions": ["Ingest"]}
|
||||
|
||||
# Delete a key
|
||||
DELETE /api/apikeys/{id}
|
||||
```
|
||||
|
||||
### 6. Manage Signals
|
||||
|
||||
```bash
|
||||
# List signals
|
||||
GET /api/signals
|
||||
|
||||
# Create a signal
|
||||
POST /api/signals
|
||||
{"Title": "Errors", "Filters": [{"Filter": "@Level = 'Error'"}]}
|
||||
```
|
||||
|
||||
### 7. Manage Dashboards & Alerts
|
||||
|
||||
Follow the same CRUD pattern at `/api/dashboards` and `/api/alerts`. Use the `/template` endpoint to get the correct JSON structure.
|
||||
|
||||
### 8. Server Diagnostics
|
||||
|
||||
```bash
|
||||
GET /api/diagnostics/status # Read permission
|
||||
GET /api/diagnostics/metrics # Project permission
|
||||
GET /api/diagnostics/ingestion # System permission
|
||||
GET /api/diagnostics/storage # Project permission
|
||||
GET /api/diagnostics/report # System permission — full diagnostic report
|
||||
```
|
||||
|
||||
### 9. User Management
|
||||
|
||||
```bash
|
||||
GET /api/users/current # Get logged-in user
|
||||
POST /api/users/login # Authenticate
|
||||
GET /api/users # List users (Project permission)
|
||||
POST /api/users # Create user (Organization permission)
|
||||
```
|
||||
|
||||
### 10. Backup
|
||||
|
||||
```bash
|
||||
POST /api/backups/immediate # Trigger immediate backup (System permission)
|
||||
GET /api/backups # List backups
|
||||
GET /api/backups/files/{name} # Download a backup file
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Ownership & Sharing Rules
|
||||
|
||||
For signals, dashboards, alerts, SQL queries, and workspaces:
|
||||
- Users can only read/modify **shared** resources and **their own** resources
|
||||
- Creating/modifying **protected** resources requires **Project** permission
|
||||
- Resources are either shared (visible to everyone), personal (owner-only), or protected (admin-managed)
|
||||
|
||||
---
|
||||
|
||||
## Response Conventions
|
||||
|
||||
- Successful list requests return a JSON array
|
||||
- Successful single-resource requests return a JSON object
|
||||
- Error responses include `{"Error": "message"}`
|
||||
- Ingestion success returns `{"MinimumLevelAccepted": null}` (or a level string if filtering is applied)
|
||||
|
||||
---
|
||||
|
||||
## Reference Files
|
||||
|
||||
For the complete endpoint listing with all paths, HTTP methods, and permission requirements, read:
|
||||
- `references/endpoints.md` — Full API endpoint table for every resource
|
||||
- `references/ingestion.md` — CLEF format specification, reified properties, status codes, and batch formatting
|
||||
|
||||
Read the appropriate reference file when you need the specific details for an endpoint or ingestion format.
|
||||
488
skills/seq-api/references/endpoints.md
Normal file
488
skills/seq-api/references/endpoints.md
Normal file
@@ -0,0 +1,488 @@
|
||||
# Seq Server API — Complete Endpoint Reference
|
||||
|
||||
This file lists every API endpoint provided by the Seq server, organized by resource group.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [api (root)](#api-root)
|
||||
2. [alerts](#alerts)
|
||||
3. [alertstate](#alertstate)
|
||||
4. [apikeys](#apikeys)
|
||||
5. [appinstances](#appinstances)
|
||||
6. [apps](#apps)
|
||||
7. [backups](#backups)
|
||||
8. [cluster](#cluster)
|
||||
9. [dashboards](#dashboards)
|
||||
10. [data (queries)](#data-queries)
|
||||
11. [deferred](#deferred)
|
||||
12. [diagnostics](#diagnostics)
|
||||
13. [events](#events)
|
||||
14. [expressionindexes](#expressionindexes)
|
||||
15. [expressions](#expressions)
|
||||
16. [feeds](#feeds)
|
||||
17. [indexes](#indexes)
|
||||
18. [licenses](#licenses)
|
||||
19. [permalinks](#permalinks)
|
||||
20. [retentionpolicies](#retentionpolicies)
|
||||
21. [roles](#roles)
|
||||
22. [runningtasks](#runningtasks)
|
||||
23. [settings](#settings)
|
||||
24. [signals](#signals)
|
||||
25. [sqlqueries](#sqlqueries)
|
||||
26. [updates](#updates)
|
||||
27. [users](#users)
|
||||
28. [workspaces](#workspaces)
|
||||
29. [health](#health)
|
||||
30. [ingestion](#ingestion)
|
||||
31. [other](#other)
|
||||
|
||||
---
|
||||
|
||||
## api (root)
|
||||
|
||||
| Path | Method | Permission |
|
||||
|------|--------|------------|
|
||||
| `api` | GET | Public |
|
||||
|
||||
Returns the root resource with links to all API resource groups.
|
||||
|
||||
---
|
||||
|
||||
## alerts
|
||||
|
||||
Manage alert definitions. Users can only access shared alerts and their own. Protected alerts require `Project` permission.
|
||||
|
||||
| Path | Method | Permission | Notes |
|
||||
|------|--------|------------|-------|
|
||||
| `api/alerts` | GET | Read | Shared + own only |
|
||||
| `api/alerts` | POST | Write | Project for protected |
|
||||
| `api/alerts/{id}` | GET | Read | Shared + own only |
|
||||
| `api/alerts/{id}` | PUT | Write | Project for protected |
|
||||
| `api/alerts/{id}` | DELETE | Write | Project for protected |
|
||||
| `api/alerts/resources` | GET | Public | |
|
||||
| `api/alerts/template` | GET | Write | |
|
||||
|
||||
---
|
||||
|
||||
## alertstate
|
||||
|
||||
| Path | Method | Permission |
|
||||
|------|--------|------------|
|
||||
| `api/alertstate` | GET | Project |
|
||||
| `api/alertstate/{id}` | GET | Project |
|
||||
| `api/alertstate/{id}` | DELETE | Project |
|
||||
| `api/alertstate/resources` | GET | Public |
|
||||
|
||||
---
|
||||
|
||||
## apikeys
|
||||
|
||||
Manage API keys. Non-Project principals can only view/manage their own keys.
|
||||
|
||||
| Path | Method | Permission | Notes |
|
||||
|------|--------|------------|-------|
|
||||
| `api/apikeys` | GET | Read | Project sees all; others own only |
|
||||
| `api/apikeys` | POST | Write | Can only delegate own permissions |
|
||||
| `api/apikeys/{id}` | GET | Read | Project sees all; others own only |
|
||||
| `api/apikeys/{id}` | PUT | Write | Can only delegate own permissions |
|
||||
| `api/apikeys/{id}` | DELETE | Write | Project removes any; others own only |
|
||||
| `api/apikeys/{id}/metrics/{measurement}` | GET | Read | Own or Project |
|
||||
| `api/apikeys/metrics/{measurement}` | GET | Project | |
|
||||
| `api/apikeys/resources` | GET | Public | |
|
||||
| `api/apikeys/template` | GET | Read | |
|
||||
|
||||
---
|
||||
|
||||
## appinstances
|
||||
|
||||
Manage installed Seq app instances. Non-Project principals see basic details only.
|
||||
|
||||
| Path | Method | Permission | Notes |
|
||||
|------|--------|------------|-------|
|
||||
| `api/appinstances` | GET | Read | Basic details without Project |
|
||||
| `api/appinstances` | POST | System | |
|
||||
| `api/appinstances/{id}` | GET | Read | Basic details without Project |
|
||||
| `api/appinstances/{id}` | PUT | System | |
|
||||
| `api/appinstances/{id}` | DELETE | System | |
|
||||
| `api/appinstances/{id}/icon` | GET | Read | |
|
||||
| `api/appinstances/{id}/invoke` | POST | Write | Must be an output app; System for non-direct-invocation |
|
||||
| `api/appinstances/{id}/metrics/{measurement}` | GET | Project | |
|
||||
| `api/appinstances/resources` | GET | Public | |
|
||||
| `api/appinstances/template` | GET | System | |
|
||||
|
||||
---
|
||||
|
||||
## apps
|
||||
|
||||
Manage app packages (install, update, remove). All require System permission.
|
||||
|
||||
| Path | Method | Permission |
|
||||
|------|--------|------------|
|
||||
| `api/apps` | GET | System |
|
||||
| `api/apps/{id}` | GET | System |
|
||||
| `api/apps/{id}` | DELETE | System |
|
||||
| `api/apps/{id}/icon` | GET | System |
|
||||
| `api/apps/{id}/update` | POST | System |
|
||||
| `api/apps/install` | POST | System |
|
||||
| `api/apps/resources` | GET | Public |
|
||||
| `api/apps/template` | GET | System |
|
||||
|
||||
---
|
||||
|
||||
## backups
|
||||
|
||||
| Path | Method | Permission | Notes |
|
||||
|------|--------|------------|-------|
|
||||
| `api/backups` | GET | System | |
|
||||
| `api/backups/{id}` | GET | System | |
|
||||
| `api/backups/files/{filename}` | GET | System | Download backup file |
|
||||
| `api/backups/immediate` | POST | System | Allows cross-site POSTs |
|
||||
| `api/backups/resources` | GET | Public | |
|
||||
|
||||
---
|
||||
|
||||
## cluster
|
||||
|
||||
| Path | Method | Permission |
|
||||
|------|--------|------------|
|
||||
| `api/cluster` | GET | System |
|
||||
| `api/cluster/{id}` | GET | System |
|
||||
| `api/cluster/{id}/drain` | POST | System |
|
||||
| `api/cluster/resources` | GET | Public |
|
||||
|
||||
---
|
||||
|
||||
## dashboards
|
||||
|
||||
Manage dashboards. Users can only access shared dashboards and their own. Protected dashboards require `Project` permission.
|
||||
|
||||
| Path | Method | Permission | Notes |
|
||||
|------|--------|------------|-------|
|
||||
| `api/dashboards` | GET | Read | Shared + own only |
|
||||
| `api/dashboards` | POST | Write | Project for protected |
|
||||
| `api/dashboards/{id}` | GET | Read | Shared + own only |
|
||||
| `api/dashboards/{id}` | PUT | Write | Project for protected |
|
||||
| `api/dashboards/{id}` | DELETE | Write | Project for protected |
|
||||
| `api/dashboards/query/template` | GET | Write | |
|
||||
| `api/dashboards/resources` | GET | Public | |
|
||||
| `api/dashboards/template` | GET | Write | |
|
||||
|
||||
---
|
||||
|
||||
## data (queries)
|
||||
|
||||
Execute SQL-style queries against the event stream.
|
||||
|
||||
| Path | Method | Permission | Notes |
|
||||
|------|--------|------------|-------|
|
||||
| `api/data` | GET | Read | Query via query params |
|
||||
| `api/data` | POST | Read | Query via JSON body |
|
||||
| `api/data/{signalId}` | GET | Read | **Obsolete** |
|
||||
| `api/data/resources` | GET | Public | |
|
||||
|
||||
---
|
||||
|
||||
## deferred
|
||||
|
||||
Retrieve results of long-running/deferred operations.
|
||||
|
||||
| Path | Method | Permission |
|
||||
|------|--------|------------|
|
||||
| `api/deferred/{deferredId}` | GET | Read |
|
||||
|
||||
---
|
||||
|
||||
## diagnostics
|
||||
|
||||
| Path | Method | Permission | Notes |
|
||||
|------|--------|------------|-------|
|
||||
| `api/diagnostics/status` | GET | Read | Basic server status |
|
||||
| `api/diagnostics/metrics` | GET | Project | |
|
||||
| `api/diagnostics/metrics/{measurement}` | GET | Project | |
|
||||
| `api/diagnostics/ingestion` | GET | System | |
|
||||
| `api/diagnostics/storage` | GET | Project | |
|
||||
| `api/diagnostics/report` | GET | System | Full diagnostic report |
|
||||
| `api/diagnostics/cluster/metrics` | GET | System | |
|
||||
| `api/diagnostics/usage-telemetry` | POST | Read | |
|
||||
| `api/diagnostics/resources` | GET | Public | |
|
||||
|
||||
---
|
||||
|
||||
## events
|
||||
|
||||
Core event operations — retrieve, search, stream, delete by signal, and raw ingestion.
|
||||
|
||||
| Path | Method | Permission | Notes |
|
||||
|------|--------|------------|-------|
|
||||
| `api/events` | GET | Read | List/search events |
|
||||
| `api/events/{id}` | GET | Read | Get single event |
|
||||
| `api/events/raw` | POST | Public* | Raw event ingestion; cross-site allowed. *Ingest required if RequireApiKeyForWritingEvents is on |
|
||||
| `api/events/scan` | GET | Read | |
|
||||
| `api/events/scan` | POST | Read | |
|
||||
| `api/events/signal` | GET | Read | |
|
||||
| `api/events/signal` | POST | Read | |
|
||||
| `api/events/signal` | DELETE | Project | Delete events matching signal |
|
||||
| `api/events/signal/{signalId}` | GET | Read | **Obsolete** |
|
||||
| `api/events/stream` | GET | Read | Live event stream (Server-Sent Events) |
|
||||
| `api/events/tabulate` | POST | Read | |
|
||||
| `api/events/tabulate/{signalId}` | GET | Read | |
|
||||
| `api/events/resources` | GET | Public | |
|
||||
|
||||
---
|
||||
|
||||
## expressionindexes
|
||||
|
||||
| Path | Method | Permission |
|
||||
|------|--------|------------|
|
||||
| `api/expressionindexes` | GET | Read |
|
||||
| `api/expressionindexes` | POST | Write |
|
||||
| `api/expressionindexes/{id}` | GET | Read |
|
||||
| `api/expressionindexes/{id}` | DELETE | Write |
|
||||
| `api/expressionindexes/resources` | GET | Public |
|
||||
| `api/expressionindexes/template` | GET | Write |
|
||||
|
||||
---
|
||||
|
||||
## expressions
|
||||
|
||||
| Path | Method | Permission |
|
||||
|------|--------|------------|
|
||||
| `api/expressions/sql` | GET | Read |
|
||||
| `api/expressions/strict` | GET | Read |
|
||||
| `api/expressions/resources` | GET | Public |
|
||||
|
||||
---
|
||||
|
||||
## feeds
|
||||
|
||||
App package feeds. All require System permission.
|
||||
|
||||
| Path | Method | Permission |
|
||||
|------|--------|------------|
|
||||
| `api/feeds` | GET | System |
|
||||
| `api/feeds` | POST | System |
|
||||
| `api/feeds/{id}` | GET | System |
|
||||
| `api/feeds/{id}` | PUT | System |
|
||||
| `api/feeds/{id}` | DELETE | System |
|
||||
| `api/feeds/resources` | GET | Public |
|
||||
| `api/feeds/template` | GET | System |
|
||||
|
||||
---
|
||||
|
||||
## indexes
|
||||
|
||||
Signal indexes. Require Project permission.
|
||||
|
||||
| Path | Method | Permission |
|
||||
|------|--------|------------|
|
||||
| `api/indexes` | GET | Project |
|
||||
| `api/indexes/{id}` | GET | Project |
|
||||
| `api/indexes/{id}` | DELETE | Project |
|
||||
| `api/indexes/resources` | GET | Public |
|
||||
|
||||
---
|
||||
|
||||
## licenses
|
||||
|
||||
| Path | Method | Permission | Notes |
|
||||
|------|--------|------------|-------|
|
||||
| `api/licenses` | GET | System | |
|
||||
| `api/licenses/{id}` | GET | Read | Read sees status; System sees certificate details |
|
||||
| `api/licenses/{id}` | PUT | System | |
|
||||
| `api/licenses/downgrade` | POST | System | |
|
||||
| `api/licenses/resources` | GET | Public | |
|
||||
|
||||
---
|
||||
|
||||
## permalinks
|
||||
|
||||
| Path | Method | Permission | Notes |
|
||||
|------|--------|------------|-------|
|
||||
| `api/permalinks` | GET | Read | Non-Project: own only |
|
||||
| `api/permalinks` | POST | Write | Non-Project: own only |
|
||||
| `api/permalinks/{id}` | GET | Read | Non-Project: own only |
|
||||
| `api/permalinks/{id}` | DELETE | Write | Non-Project: own only |
|
||||
| `api/permalinks/resources` | GET | Public | |
|
||||
| `api/permalinks/template` | GET | Write | |
|
||||
|
||||
---
|
||||
|
||||
## retentionpolicies
|
||||
|
||||
All require Project permission.
|
||||
|
||||
| Path | Method | Permission |
|
||||
|------|--------|------------|
|
||||
| `api/retentionpolicies` | GET | Project |
|
||||
| `api/retentionpolicies` | POST | Project |
|
||||
| `api/retentionpolicies/{id}` | GET | Project |
|
||||
| `api/retentionpolicies/{id}` | PUT | Project |
|
||||
| `api/retentionpolicies/{id}` | DELETE | Project |
|
||||
| `api/retentionpolicies/resources` | GET | Public |
|
||||
| `api/retentionpolicies/template` | GET | Project |
|
||||
|
||||
---
|
||||
|
||||
## roles
|
||||
|
||||
| Path | Method | Permission |
|
||||
|------|--------|------------|
|
||||
| `api/roles` | GET | Read |
|
||||
| `api/roles/{id}` | GET | Read |
|
||||
| `api/roles/resources` | GET | Public |
|
||||
|
||||
---
|
||||
|
||||
## runningtasks
|
||||
|
||||
| Path | Method | Permission |
|
||||
|------|--------|------------|
|
||||
| `api/runningtasks` | GET | System |
|
||||
| `api/runningtasks/{id}` | GET | System |
|
||||
| `api/runningtasks/{id}` | DELETE | System |
|
||||
| `api/runningtasks/resources` | GET | Public |
|
||||
|
||||
---
|
||||
|
||||
## settings
|
||||
|
||||
Server settings. Most require System permission. Notable publicly accessible settings:
|
||||
|
||||
| Path | Method | Permission | Notes |
|
||||
|------|--------|------------|-------|
|
||||
| `api/settings/{id}` | GET | System | Generic setting |
|
||||
| `api/settings/{id}` | PUT | System | |
|
||||
| `api/settings/setting-authenticationprovider` | GET | Public | |
|
||||
| `api/settings/setting-instancetitle` | GET | Public | |
|
||||
| `api/settings/setting-isauthenticationenabled` | GET | Public | |
|
||||
| `api/settings/setting-isactivedirectoryauthentication` | GET | Public | |
|
||||
| `api/settings/setting-isusagetelemetryenabled` | GET | Read | |
|
||||
| `api/settings/setting-searchdurationseconds` | GET | Read | |
|
||||
| `api/settings/setting-searchdurationseconds` | PUT | System | |
|
||||
| `api/settings/setting-servicenameexpression` | GET | Read | |
|
||||
| `api/settings/setting-servicenameexpression` | PUT | Project | |
|
||||
| `api/settings/setting-requireapikeyforwritingevents` | GET | Project | |
|
||||
| `api/settings/setting-requireapikeyforwritingevents` | PUT | Project | |
|
||||
| `api/settings/setting-newusershowdashboardids` | GET/PUT | Organization | |
|
||||
| `api/settings/setting-newusershowqueryids` | GET/PUT | Organization | |
|
||||
| `api/settings/setting-newusershowsignalids` | GET/PUT | Organization | |
|
||||
| `api/settings/setting-checkforupdates` | GET/PUT | System | |
|
||||
| `api/settings/setting-minimumfreestoragespace` | GET/PUT | System | |
|
||||
| `api/settings/setting-raweventmaximumcontentlength` | GET/PUT | System | |
|
||||
| `api/settings/setting-rawpayloadmaximumcontentlength` | GET/PUT | System | |
|
||||
| `api/settings/setting-themestyles` | GET/PUT | System | |
|
||||
| `api/settings/internal-error-reporting` | GET/PUT | System | |
|
||||
| `api/settings/resources` | GET | Public | |
|
||||
|
||||
---
|
||||
|
||||
## signals
|
||||
|
||||
Saved signals. Users can only access shared signals and their own. Protected signals require `Project` permission.
|
||||
|
||||
| Path | Method | Permission | Notes |
|
||||
|------|--------|------------|-------|
|
||||
| `api/signals` | GET | Read | Shared + own only |
|
||||
| `api/signals` | POST | Write | Project for protected |
|
||||
| `api/signals/{id}` | GET | Read | Shared + own only |
|
||||
| `api/signals/{id}` | PUT | Write | Project for protected |
|
||||
| `api/signals/{id}` | DELETE | Write | Project for protected |
|
||||
| `api/signals/resources` | GET | Public | |
|
||||
| `api/signals/template` | GET | Write | |
|
||||
|
||||
---
|
||||
|
||||
## sqlqueries
|
||||
|
||||
Saved SQL queries. Same ownership/sharing rules as signals.
|
||||
|
||||
| Path | Method | Permission | Notes |
|
||||
|------|--------|------------|-------|
|
||||
| `api/sqlqueries` | GET | Read | Shared + own only |
|
||||
| `api/sqlqueries` | POST | Write | Project for protected |
|
||||
| `api/sqlqueries/{id}` | GET | Read | Shared + own only |
|
||||
| `api/sqlqueries/{id}` | PUT | Write | Project for protected |
|
||||
| `api/sqlqueries/{id}` | DELETE | Write | Project for protected |
|
||||
| `api/sqlqueries/resources` | GET | Public | |
|
||||
| `api/sqlqueries/template` | GET | Write | |
|
||||
|
||||
---
|
||||
|
||||
## updates
|
||||
|
||||
| Path | Method | Permission |
|
||||
|------|--------|------------|
|
||||
| `api/updates` | GET | System |
|
||||
| `api/updates/{id}` | GET | System |
|
||||
| `api/updates/resources` | GET | Public |
|
||||
|
||||
---
|
||||
|
||||
## users
|
||||
|
||||
| Path | Method | Permission | Notes |
|
||||
|------|--------|------------|-------|
|
||||
| `api/users` | GET | Project | System for auth provider info |
|
||||
| `api/users` | POST | Organization | Cannot grant permissions you don't have |
|
||||
| `api/users/{id}` | GET | Public | Own record; Project for others |
|
||||
| `api/users/{id}` | PUT | Public | Own limited fields; Organization for others |
|
||||
| `api/users/{id}` | DELETE | Organization | |
|
||||
| `api/users/{id}/searches` | GET | Read | Own search history only |
|
||||
| `api/users/{id}/searches` | DELETE | Write | Own search history only |
|
||||
| `api/users/{id}/searches/update` | POST | Write | Own search history only |
|
||||
| `api/users/{id}/unlinkauthenticationprovider` | POST | System | |
|
||||
| `api/users/current` | GET | Public | Logged-in user only |
|
||||
| `api/users/login` | POST | Public | |
|
||||
| `api/users/logout` | POST | Public | Allows cross-site POSTs |
|
||||
| `api/users/providers` | GET | Public | |
|
||||
| `api/users/resources` | GET | Public | |
|
||||
| `api/users/template` | GET | Organization | |
|
||||
|
||||
---
|
||||
|
||||
## workspaces
|
||||
|
||||
Same ownership/sharing rules as signals, dashboards, etc.
|
||||
|
||||
| Path | Method | Permission | Notes |
|
||||
|------|--------|------------|-------|
|
||||
| `api/workspaces` | GET | Read | Shared + own only |
|
||||
| `api/workspaces` | POST | Write | Project for protected |
|
||||
| `api/workspaces/{id}` | GET | Read | Shared + own only |
|
||||
| `api/workspaces/{id}` | PUT | Write | Project for protected |
|
||||
| `api/workspaces/{id}` | DELETE | Write | Project for protected |
|
||||
| `api/workspaces/resources` | GET | Public | |
|
||||
| `api/workspaces/template` | GET | Write | |
|
||||
|
||||
---
|
||||
|
||||
## health
|
||||
|
||||
| Path | Method | Permission | Notes |
|
||||
|------|--------|------------|-------|
|
||||
| `health` | GET | Public | Returns 200 or 503 |
|
||||
| `health/cluster` | GET | Public | Cluster health |
|
||||
|
||||
---
|
||||
|
||||
## ingestion
|
||||
|
||||
| Path | Method | Permission | Notes |
|
||||
|------|--------|------------|-------|
|
||||
| `ingest/clef` | POST | Public* | CLEF format; cross-site allowed |
|
||||
| `ingest/otlp/v1/logs` | POST | Public* | OpenTelemetry logs |
|
||||
| `ingest/otlp/v1/traces` | POST | Public* | OpenTelemetry traces |
|
||||
| `ingest/otlp/v1/metrics` | POST | Public* | OpenTelemetry metrics |
|
||||
|
||||
*If `RequireApiKeyForWritingEvents` is enabled, Ingest permission is required.
|
||||
|
||||
---
|
||||
|
||||
## other
|
||||
|
||||
| Path | Method | Permission | Notes |
|
||||
|------|--------|------------|-------|
|
||||
| `integrated` | GET | Public | Windows integrated auth |
|
||||
| `oidc/challenge` | GET | Public | OpenID Connect |
|
||||
| `oidc/challenge` | POST | Public | OpenID Connect |
|
||||
| `theme/styles.css` | GET | Public | Custom theme CSS |
|
||||
144
skills/seq-api/references/ingestion.md
Normal file
144
skills/seq-api/references/ingestion.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# Seq Ingestion Reference — CLEF Format & HTTP Details
|
||||
|
||||
## Endpoint
|
||||
|
||||
```
|
||||
POST {SEQ_URL}/ingest/clef
|
||||
```
|
||||
|
||||
## Headers
|
||||
|
||||
| Header | Value | Required |
|
||||
|--------|-------|----------|
|
||||
| `Content-Type` | `application/vnd.serilog.clef` (batch) or `application/json` (single event) | Yes |
|
||||
| `X-Seq-ApiKey` | Your API key | Only if `RequireApiKeyForWritingEvents` is enabled |
|
||||
|
||||
Alternatively, the API key can be passed as a query parameter: `?apiKey={key}`
|
||||
|
||||
## CLEF Format
|
||||
|
||||
Events are newline-delimited JSON documents (one JSON object per line). Each object represents one log event.
|
||||
|
||||
### Batch Example
|
||||
|
||||
```
|
||||
{"@t":"2024-01-15T10:30:00.000Z","@mt":"Hello, {User}","User":"alice"}
|
||||
{"@t":"2024-01-15T10:30:01.123Z","@mt":"Processing order {OrderId}","OrderId":42,"@l":"Information"}
|
||||
{"@t":"2024-01-15T10:30:02.456Z","@mt":"Failed to process {OrderId}","OrderId":42,"@l":"Error","@x":"System.Exception: Something went wrong\n at MyApp.OrderProcessor.Process()"}
|
||||
```
|
||||
|
||||
### Reified Properties (Special @ Properties)
|
||||
|
||||
Any JSON property at the top level is treated as a regular event property, **except** the following special properties:
|
||||
|
||||
| Property | Name | Description | Required? |
|
||||
|----------|------|-------------|-----------|
|
||||
| `@t` | Timestamp | ISO 8601 timestamp | **Yes** |
|
||||
| `@m` | Message | Fully-rendered message text | No (use `@mt` or `@m`) |
|
||||
| `@mt` | Message Template | [Message template](http://messagetemplates.org) with named holes like `{User}` | No (alternative to `@m`) |
|
||||
| `@l` | Level | Log level string: `Verbose`, `Debug`, `Information`, `Warning`, `Error`, `Fatal` | No (defaults to Information) |
|
||||
| `@x` | Exception | Error/backtrace as a string | No |
|
||||
| `@i` | Event ID | Event type identifier (numeric or hex string) | No |
|
||||
| `@r` | Renderings | Pre-rendered values for format tokens in `@mt` | No |
|
||||
| `@tr` | Trace ID | Groups spans/logs in the same trace | Required for spans |
|
||||
| `@sp` | Span ID | Unique span identifier | Required for spans |
|
||||
| `@ps` | Parent Span ID | Parent span's ID; absent = root span | No |
|
||||
| `@st` | Span Start | ISO 8601 start timestamp of the span | Required for spans |
|
||||
| `@sc` | Instrumentation Scope | App-local component name | No |
|
||||
| `@ra` | Resource Attributes | System-level component descriptor | No |
|
||||
| `@sk` | Span Kind | `Client`, `Server`, `Internal`, `Producer`, or `Consumer` | No |
|
||||
|
||||
### Escaping @ in Property Names
|
||||
|
||||
To use a property name starting with `@`, double it: `@@myProp` becomes `@myProp` in Seq.
|
||||
|
||||
### Batch Delimiters
|
||||
|
||||
Use `\n` or `\r\n` between JSON objects. No trailing delimiter is required but is harmless.
|
||||
|
||||
## Status Codes
|
||||
|
||||
| Code | Meaning |
|
||||
|------|---------|
|
||||
| **201** Created | Events ingested successfully |
|
||||
| **400** Bad Request | Malformed payload or event exceeds max size |
|
||||
| **401** Unauthorized | API key missing or invalid |
|
||||
| **403** Forbidden | API key lacks Ingest permission |
|
||||
| **413** Request Entity Too Large | Payload exceeds configured max size |
|
||||
| **500** Internal Server Error | Server-side error; check Seq diagnostics |
|
||||
| **503** Service Unavailable | Server starting up, or storage space below threshold |
|
||||
|
||||
## Response Format
|
||||
|
||||
### Success (201)
|
||||
|
||||
```json
|
||||
{"MinimumLevelAccepted": null}
|
||||
```
|
||||
|
||||
`MinimumLevelAccepted` will be one of `Verbose`, `Debug`, `Information`, `Warning`, `Error`, `Fatal` if a level filter is applied to the API key, or `null` if no filtering. Clients can use this to pre-filter events and reduce bandwidth.
|
||||
|
||||
### Error (4xx/5xx)
|
||||
|
||||
```json
|
||||
{"Error": "Description of what went wrong"}
|
||||
```
|
||||
|
||||
## OpenTelemetry Ingestion
|
||||
|
||||
Seq also accepts OpenTelemetry Protocol (OTLP) payloads:
|
||||
|
||||
| Path | Purpose |
|
||||
|------|---------|
|
||||
| `ingest/otlp/v1/logs` | OTLP logs |
|
||||
| `ingest/otlp/v1/traces` | OTLP traces |
|
||||
| `ingest/otlp/v1/metrics` | OTLP metrics |
|
||||
|
||||
These follow the standard OTLP HTTP specification. The same API key authentication rules apply.
|
||||
|
||||
## Raw Events Endpoint (Legacy)
|
||||
|
||||
The older `api/events/raw` endpoint also accepts event ingestion with cross-site POST support. The `/ingest/clef` endpoint is preferred for new integrations.
|
||||
|
||||
## Common curl Examples
|
||||
|
||||
### Send a single event
|
||||
|
||||
```bash
|
||||
curl -X POST "https://seq.example.com/ingest/clef" \
|
||||
-H "Content-Type: application/vnd.serilog.clef" \
|
||||
-H "X-Seq-ApiKey: YOUR_API_KEY" \
|
||||
-d '{"@t":"2024-01-15T10:30:00Z","@mt":"Deployment started for {App}","App":"myservice","@l":"Information"}'
|
||||
```
|
||||
|
||||
### Send a batch
|
||||
|
||||
```bash
|
||||
curl -X POST "https://seq.example.com/ingest/clef" \
|
||||
-H "Content-Type: application/vnd.serilog.clef" \
|
||||
-H "X-Seq-ApiKey: YOUR_API_KEY" \
|
||||
-d '{"@t":"2024-01-15T10:30:00Z","@mt":"Step 1 complete","@l":"Information"}
|
||||
{"@t":"2024-01-15T10:30:01Z","@mt":"Step 2 complete","@l":"Information"}
|
||||
{"@t":"2024-01-15T10:30:02Z","@mt":"All steps done","@l":"Information"}'
|
||||
```
|
||||
|
||||
### Send with an API key in the query string
|
||||
|
||||
```bash
|
||||
curl -X POST "https://seq.example.com/ingest/clef?apiKey=YOUR_API_KEY" \
|
||||
-H "Content-Type: application/vnd.serilog.clef" \
|
||||
-d '{"@t":"2024-01-15T10:30:00Z","@mt":"Hello from curl"}'
|
||||
```
|
||||
|
||||
### Query events via the data API
|
||||
|
||||
```bash
|
||||
curl "https://seq.example.com/api/data?q=select%20count(*)%20from%20stream%20group%20by%20%40Level&rangeStartUtc=2024-01-01&rangeEndUtc=2024-01-02" \
|
||||
-H "X-Seq-ApiKey: YOUR_API_KEY"
|
||||
```
|
||||
|
||||
### Check server health
|
||||
|
||||
```bash
|
||||
curl https://seq.example.com/health
|
||||
```
|
||||
Reference in New Issue
Block a user