sophhub 0.1.0

package/skills/builtin/sophnet-customer-management/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: sophnet-customer-management
+description: >
+  客户管理助手：支持上传 Excel/CSV/Markdown 客户表创建客户库，使用自然语言创建字段、添加客户、
+  查询筛选、修改删除客户，并生成生日/到期/跟进提醒。当用户要管理客户资料、导入客户名单、
+  查询某月生日客户、查 30 天内到期客户、修改客户信息、导出客户数据时使用。
+---
+
+# 客户管理助手
+
+这个 skill 面向“成长型小微企业主”的轻量客户管理场景。优先用对话驱动，但所有关键写操作都要经过结构化命令和必要确认。
+
+## 关键原则
+
+- 先预览、后写入：导入文件时，先做预览，再让用户确认写入。
+- 删除和批量修改必须确认：不要在重名或模糊命中时直接执行。
+- 统一使用 Python CLI：所有确定性操作通过 `uv run --project "{baseDir}" python -m customer_mgmt_cli ...` 执行。
+- 数据以 SQLite 为主：客户库主数据默认写到用户运行环境配置中的数据库路径；JSON/Markdown 只作为预览、中间结果和展示格式。
+
+## 首次使用初始化
+
+- 第一次使用本 skill 时，先初始化运行时配置文件：`${HOME}/.config/sophnet-customer-management/config.env`。
+- 配置文件中至少保存：
+  - `CUSTOMER_MGMT_DB_PATH=<sqlite绝对路径>`
+- 如果用户没有指定数据库路径，则默认写为：`${HOME}/.config/sophnet-customer-management/customer_mgmt.sqlite3`
+- 初始化方式：
+  - 第一次调用 CLI 时，如果显式传了 `--db`，CLI 会自动把该路径写入 `config.env`
+  - 如果没有传 `--db` 且 `config.env` 还不存在，CLI 会自动创建 `config.env` 并写入默认路径
+- 后续使用本 skill 时：
+  - 默认先读取 `${HOME}/.config/sophnet-customer-management/config.env`
+  - 从 `CUSTOMER_MGMT_DB_PATH` 获取 SQLite 路径
+  - 因此后续命令默认不必重复传 `--db`
+- 这样即使后续卸载或替换 skill 目录，默认客户数据仍然保留在用户配置目录，不会跟随 skill 一起被删除。
+
+### 首次初始化操作规范
+
+- 当 agent 判断这是用户第一次使用本 skill，或当前环境中还不存在 `${HOME}/.config/sophnet-customer-management/config.env` 时，应把本轮视为“首次初始化 + 当前请求”两步一起完成，而不是单独把初始化抛给用户。
+- 默认策略：
+  - 不额外追问数据库路径
+  - 直接采用默认路径 `${HOME}/.config/sophnet-customer-management/customer_mgmt.sqlite3`
+  - 首次 CLI 调用后自动落盘 `config.env`
+- 只有在用户明确提出“数据库放到别的位置”“想自己指定路径”“多套客户库分开存”等要求时，才改为显式传 `--db <custom_path>`。
+- 初始化完成后，agent 在回复中可顺带告知一次数据库位置，但不要每次都重复强调。
+- 后续同一 skill 内的命令默认不再传 `--db`，除非本轮任务明确要求切换数据库。
+
+### 首次初始化示例对话
+
+#### 示例 1：用户第一次直接开始用
+
+用户：
+
+```text
+帮我建一个客户表，先有姓名、手机号、生日、微信、备注。
+```
+
+agent 内部执行思路：
+
+- 先检查 `${HOME}/.config/sophnet-customer-management/config.env` 是否存在。
+- 若不存在，则认定为首次使用。
+- 不必先打断用户去确认数据库路径，直接使用默认路径 `${HOME}/.config/sophnet-customer-management/customer_mgmt.sqlite3`。
+- 执行首次 CLI 调用；CLI 会自动创建：
+  - `${HOME}/.config/sophnet-customer-management/config.env`
+  - `${HOME}/.config/sophnet-customer-management/customer_mgmt.sqlite3`
+- 然后继续执行本次真实任务，例如：
+
+```bash
+uv run --project "{baseDir}" python -m customer_mgmt_cli \
+  schema evolve --json '{"labels":["微信"]}'
+```
+
+agent 对用户的推荐回复风格：
+
+```text
+我先帮你初始化客户库，并按默认位置保存，后续都会自动复用这份客户库。
+这次会先创建基础客户表，并补一个“微信”字段。
+```
+
+#### 示例 2：用户明确指定数据库位置
+
+用户：
+
+```text
+这个客户库不要放默认位置，放到 /data/business/customer_a.sqlite3。
+```
+
+agent 内部执行思路：
+
+- 识别为“用户显式指定路径”。
+- 本次调用必须显式带上 `--db /data/business/customer_a.sqlite3`。
+- CLI 执行后，会把该路径写入 `${HOME}/.config/sophnet-customer-management/config.env`。
+- 后续若无新的指定，就默认继续使用这个路径。
+
+示例命令：
+
+```bash
+uv run --project "{baseDir}" python -m customer_mgmt_cli \
+  --db /data/business/customer_a.sqlite3 \
+  schema inspect
+```
+
+#### 示例 3：后续再次使用
+
+用户：
+
+```text
+查一下这个月过生日的客户。
+```
+
+agent 内部执行思路：
+
+- 默认先读取 `${HOME}/.config/sophnet-customer-management/config.env`
+- 取出 `CUSTOMER_MGMT_DB_PATH`
+- 直接执行查询，不再重新询问数据库路径
+
+```bash
+uv run --project "{baseDir}" python -m customer_mgmt_cli \
+  customer query --json '{"birthday_month":3,"limit":20}'
+```
+
+## 可处理的输入
+
+- 自然语言：
+  - “添加客户张三，电话 138xxxx”
+  - “查一下 3 月过生日的客户”
+  - “把张三的电话改成 139xxxx”
+  - “帮我建一个客户表，字段有姓名、电话、生日、备注”
+- 文件：
+  - `.xls`
+  - `.xlsx`
+  - `.csv`
+  - `.md`
+
+## 文件导入流程
+
+### Step 1：定位文件
+
+用户上传文件后，优先在当前 agent 工作路径（working directory）下的 `media/inbound/` 中寻找最新文件；
+若用户直接给了路径，则直接使用该路径。
+
+### Step 2：预览导入
+
+```bash
+uv run --project "{baseDir}" python -m customer_mgmt_cli \
+  import file --path "<file_path>"
+```
+
+- 读取返回 JSON 里的 `summary`
+- 向用户展示：
+  - 待导入客户数
+  - 待导入业务记录数
+  - 新增字段数
+  - 异常与告警
+- 仅当用户确认后再执行真正写入
+
+### Step 3：确认后写入
+
+```bash
+uv run --project "{baseDir}" python -m customer_mgmt_cli \
+  import file --path "<file_path>" --commit
+```
+
+## 自然语言创建字段
+
+当用户要求“建一个客户表”或“新增某个字段”时，抽取字段名称，然后执行：
+
+```bash
+uv run --project "{baseDir}" python -m customer_mgmt_cli \
+  schema evolve --json '{"labels":["微信","孩子生日","最近消费"]}'
+```
+
+先向用户解释将新增哪些字段，再执行。
+
+查看当前字段：
+
+```bash
+uv run --project "{baseDir}" python -m customer_mgmt_cli \
+  schema inspect
+```
+
+## 新增客户
+
+```bash
+uv run --project "{baseDir}" python -m customer_mgmt_cli \
+  customer add --json '{
+    "name":"张三",
+    "primary_phone":"13800138000",
+    "birthday":"1988-03-18",
+    "tags":["VIP"],
+    "notes":"老客户",
+    "dynamic_fields":{"微信":"zhangsan88","喜欢项目":"补水"}
+  }'
+```
+
+## 查询客户
+
+按姓名/手机号查：
+
+```bash
+uv run --project "{baseDir}" python -m customer_mgmt_cli \
+  customer query --json '{"name":"张三","limit":10}'
+```
+
+查本月生日：
+
+```bash
+uv run --project "{baseDir}" python -m customer_mgmt_cli \
+  customer query --json '{"birthday_month":3,"limit":20}'
+```
+
+查 30 天内到期：
+
+```bash
+uv run --project "{baseDir}" python -m customer_mgmt_cli \
+  customer query --json '{"due_within_days":30,"limit":20}'
+```
+
+返回结果中会带 Markdown 预览，可直接展示给用户。
+
+## 修改客户
+
+更新前先查，确认命中唯一客户后再执行：
+
+```bash
+uv run --project "{baseDir}" python -m customer_mgmt_cli \
+  customer update \
+  --match-json '{"name":"张三"}' \
+  --updates-json '{"primary_phone":"13900139000","dynamic_fields":{"孩子生日":"2018-03-01"}}'
+```
+
+## 删除客户
+
+删除必须二次确认：
+
+```bash
+uv run --project "{baseDir}" python -m customer_mgmt_cli \
+  customer delete --match-json '{"name":"张三"}'
+```
+
+## 提醒
+
+先规划提醒，再决定是否真正注册到 OpenClaw cron。
+
+规划生日和到期提醒：
+
+```bash
+uv run --project "{baseDir}" python -m customer_mgmt_cli \
+  reminder plan --json '{"kinds":["birthday","due_date"]}'
+```
+
+确认后创建提醒：
+
+```bash
+uv run --project "{baseDir}" python -m customer_mgmt_cli \
+  reminder schedule --json '{"kinds":["birthday","due_date"]}'
+```
+
+单个客户跟进提醒：
+
+```bash
+uv run --project "{baseDir}" python -m customer_mgmt_cli \
+  reminder plan --json '{"follow_up":{"match":{"name":"张三"},"date":"2026-03-20"}}'
+```
+
+## 导出
+
+优先导出 CSV，必要时再导出 XLSX：
+
+```bash
+uv run --project "{baseDir}" python -m customer_mgmt_cli \
+  export file --output "{baseDir}/data/customers_export.csv"
+```

package/skills/builtin/sophnet-customer-management/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "sophnet-customer-management"
+version = "1.0.0"
+description = "Customer management skill core and CLI"
+requires-python = ">=3.10"
+dependencies = [
+    "openpyxl>=3.1.0",
+    "xlrd>=2.0.1",
+]
+
+[project.scripts]
+customer-mgmt = "customer_mgmt_cli.cli:main"
+
+[tool.uv]
+package = true

package/skills/builtin/sophnet-customer-management/src/customer_mgmt_cli/__init__.py

@@ -0,0 +1,2 @@
+"""Customer management CLI package."""
+

package/skills/builtin/sophnet-customer-management/src/customer_mgmt_cli/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/builtin/sophnet-customer-management/src/customer_mgmt_cli/cli.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from customer_mgmt_core.service import CustomerManagementService
+
+from .commands import customer, export_file, import_file, reminder, schema
+from .config import CONFIG_FILE, resolve_db_path
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="客户管理 CLI")
+    parser.add_argument(
+        "--db",
+        default=None,
+        help="SQLite 数据库路径；不传时优先读取 ~/.config/sophnet-customer-management/config.env",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    schema.register(subparsers)
+    import_file.register(subparsers)
+    customer.register(subparsers)
+    reminder.register(subparsers)
+    export_file.register(subparsers)
+    return parser
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+    db_path = resolve_db_path(args.db)
+    service = CustomerManagementService(db_path)
+    try:
+        result = args.handler(args, service)
+    except Exception as exc:  # noqa: BLE001
+        print(
+            json.dumps(
+                {
+                    "ok": False,
+                    "db_path": str(db_path),
+                    "config_file": str(CONFIG_FILE),
+                    "error": str(exc),
+                },
+                ensure_ascii=False,
+                indent=2,
+            )
+        )
+        return 1
+
+    print(
+        json.dumps(
+            {
+                "ok": True,
+                "db_path": str(db_path),
+                "config_file": str(CONFIG_FILE),
+                "result": result,
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/builtin/sophnet-customer-management/src/customer_mgmt_cli/commands/__init__.py

@@ -0,0 +1,2 @@
+"""CLI command modules."""
+

package/skills/builtin/sophnet-customer-management/src/customer_mgmt_cli/commands/customer.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import json
+
+
+def register(subparsers) -> None:
+    customer_parser = subparsers.add_parser("customer", help="客户增删改查")
+    customer_subparsers = customer_parser.add_subparsers(dest="customer_action", required=True)
+
+    add_parser = customer_subparsers.add_parser("add", help="新增客户")
+    add_parser.add_argument("--json", dest="payload_json", required=True)
+    add_parser.set_defaults(handler=handle_add)
+
+    update_parser = customer_subparsers.add_parser("update", help="更新客户")
+    update_parser.add_argument("--match-json", required=True)
+    update_parser.add_argument("--updates-json", required=True)
+    update_parser.set_defaults(handler=handle_update)
+
+    delete_parser = customer_subparsers.add_parser("delete", help="删除客户")
+    delete_parser.add_argument("--match-json", required=True)
+    delete_parser.set_defaults(handler=handle_delete)
+
+    query_parser = customer_subparsers.add_parser("query", help="查询客户")
+    query_parser.add_argument("--json", dest="payload_json", required=True)
+    query_parser.set_defaults(handler=handle_query)
+
+    record_add_parser = customer_subparsers.add_parser("record-add", help="新增业务记录")
+    record_add_parser.add_argument("--json", dest="payload_json", required=True)
+    record_add_parser.set_defaults(handler=handle_record_add)
+
+    record_query_parser = customer_subparsers.add_parser("record-query", help="查询业务记录")
+    record_query_parser.add_argument("--json", dest="payload_json", required=True)
+    record_query_parser.set_defaults(handler=handle_record_query)
+
+
+def handle_add(args, service):
+    return service.add_customer(json.loads(args.payload_json))
+
+
+def handle_update(args, service):
+    return service.update_customer(
+        json.loads(args.match_json),
+        json.loads(args.updates_json),
+    )
+
+
+def handle_delete(args, service):
+    return service.delete_customer(json.loads(args.match_json))
+
+
+def handle_query(args, service):
+    return service.query_customers(json.loads(args.payload_json))
+
+
+def handle_record_add(args, service):
+    return service.add_record(json.loads(args.payload_json))
+
+
+def handle_record_query(args, service):
+    return service.query_records(json.loads(args.payload_json))

package/skills/builtin/sophnet-customer-management/src/customer_mgmt_cli/commands/export_file.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import json
+
+
+def register(subparsers) -> None:
+    export_parser = subparsers.add_parser("export", help="导出客户数据")
+    export_subparsers = export_parser.add_subparsers(dest="export_action", required=True)
+
+    file_parser = export_subparsers.add_parser("file", help="导出到文件")
+    file_parser.add_argument("--output", required=True)
+    file_parser.add_argument("--json", dest="payload_json")
+    file_parser.set_defaults(handler=handle_export_file)
+
+
+def handle_export_file(args, service):
+    payload = json.loads(args.payload_json) if args.payload_json else {}
+    return service.export_customers(args.output, payload)

package/skills/builtin/sophnet-customer-management/src/customer_mgmt_cli/commands/import_file.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+
+def register(subparsers) -> None:
+    import_parser = subparsers.add_parser("import", help="导入客户文件")
+    import_subparsers = import_parser.add_subparsers(dest="import_action", required=True)
+
+    file_parser = import_subparsers.add_parser("file", help="导入文件")
+    file_parser.add_argument("--path", required=True)
+    file_parser.add_argument("--commit", action="store_true")
+    file_parser.set_defaults(handler=handle_import_file)
+
+
+def handle_import_file(args, service):
+    return service.import_file(args.path, commit=args.commit)

package/skills/builtin/sophnet-customer-management/src/customer_mgmt_cli/commands/reminder.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import json
+
+
+def register(subparsers) -> None:
+    reminder_parser = subparsers.add_parser("reminder", help="提醒规划与创建")
+    reminder_subparsers = reminder_parser.add_subparsers(dest="reminder_action", required=True)
+
+    plan_parser = reminder_subparsers.add_parser("plan", help="生成提醒计划")
+    plan_parser.add_argument("--json", dest="payload_json", required=True)
+    plan_parser.set_defaults(handler=handle_plan)
+
+    schedule_parser = reminder_subparsers.add_parser("schedule", help="生成并注册提醒")
+    schedule_parser.add_argument("--json", dest="payload_json", required=True)
+    schedule_parser.set_defaults(handler=handle_schedule)
+
+
+def handle_plan(args, service):
+    return service.plan_reminders(json.loads(args.payload_json))
+
+
+def handle_schedule(args, service):
+    payload = json.loads(args.payload_json)
+    payload["schedule"] = True
+    return service.plan_reminders(payload)

package/skills/builtin/sophnet-customer-management/src/customer_mgmt_cli/commands/schema.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import json
+
+
+def register(subparsers) -> None:
+    schema_parser = subparsers.add_parser("schema", help="查看或演进字段定义")
+    schema_subparsers = schema_parser.add_subparsers(dest="schema_action", required=True)
+
+    inspect_parser = schema_subparsers.add_parser("inspect", help="查看当前 schema")
+    inspect_parser.set_defaults(handler=handle_inspect)
+
+    evolve_parser = schema_subparsers.add_parser("evolve", help="新增动态字段")
+    evolve_parser.add_argument("--labels", nargs="*", default=[])
+    evolve_parser.add_argument("--json", dest="payload_json")
+    evolve_parser.set_defaults(handler=handle_evolve)
+
+
+def handle_inspect(args, service):
+    return service.inspect_schema()
+
+
+def handle_evolve(args, service):
+    labels = list(args.labels)
+    if args.payload_json:
+        payload = json.loads(args.payload_json)
+        labels.extend(payload.get("labels", []))
+    return service.evolve_schema(labels)

package/skills/builtin/sophnet-customer-management/src/customer_mgmt_cli/config.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+CONFIG_DIR = Path.home() / ".config" / "sophnet-customer-management"
+CONFIG_FILE = CONFIG_DIR / "config.env"
+DEFAULT_DB_FILE = CONFIG_DIR / "customer_mgmt.sqlite3"
+DB_PATH_KEY = "CUSTOMER_MGMT_DB_PATH"
+
+
+def resolve_db_path(cli_db: str | None) -> Path:
+    if cli_db:
+        db_path = Path(cli_db).expanduser()
+        persist_db_path(db_path)
+        return db_path
+
+    env_db = load_env_value(DB_PATH_KEY)
+    if env_db:
+        return Path(env_db).expanduser()
+
+    default_db = DEFAULT_DB_FILE
+    persist_db_path(default_db)
+    return default_db
+
+
+def persist_db_path(db_path: Path) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    entries = load_env_entries()
+    entries[DB_PATH_KEY] = str(db_path.expanduser().resolve())
+    lines = ["# sophnet-customer-management runtime config"]
+    lines.extend(f"{key}={value}" for key, value in sorted(entries.items()))
+    CONFIG_FILE.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def load_env_value(key: str) -> str | None:
+    value = load_env_entries().get(key)
+    if value:
+        return value
+    return os.environ.get(key)
+
+
+def load_env_entries() -> dict[str, str]:
+    if not CONFIG_FILE.exists():
+        return {}
+    entries: dict[str, str] = {}
+    for raw_line in CONFIG_FILE.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        entries[key.strip()] = value.strip()
+    return entries

package/skills/builtin/sophnet-customer-management/src/customer_mgmt_core/__init__.py

@@ -0,0 +1,2 @@
+"""Customer management core package."""
+

package/skills/builtin/sophnet-customer-management/src/customer_mgmt_core/exporter.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import csv
+import json
+from pathlib import Path
+from typing import Any
+
+import openpyxl
+
+
+def flatten_customers(customers: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    rows: list[dict[str, Any]] = []
+    for customer in customers:
+        row = {
+            "客户ID": customer["customer_id"],
+            "姓名": customer.get("name"),
+            "手机号": customer.get("primary_phone"),
+            "生日": customer.get("birthday"),
+            "标签": "，".join(customer.get("tags", [])),
+            "备注": customer.get("notes"),
+            "最近更新时间": customer.get("updated_at"),
+        }
+        for field_key, item in customer.get("dynamic_field_map", {}).items():
+            row[item.get("label") or field_key] = item.get("displayValue") or item.get("value")
+        rows.append(row)
+    return rows
+
+
+def export_customers(customers: list[dict[str, Any]], output_path: str | Path) -> dict[str, Any]:
+    path = Path(output_path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    rows = flatten_customers(customers)
+    if path.suffix.lower() == ".csv":
+        _write_csv(rows, path)
+    elif path.suffix.lower() == ".xlsx":
+        _write_xlsx(rows, path)
+    elif path.suffix.lower() == ".json":
+        path.write_text(json.dumps(rows, ensure_ascii=False, indent=2), encoding="utf-8")
+    else:
+        raise ValueError("仅支持导出为 .csv / .xlsx / .json")
+    return {"output_path": str(path), "row_count": len(rows)}
+
+
+def preview_as_markdown(customers: list[dict[str, Any]], limit: int = 20) -> str:
+    rows = flatten_customers(customers)[:limit]
+    if not rows:
+        return "暂无客户数据。"
+    headers = list(rows[0].keys())
+    lines = [
+        "| " + " | ".join(headers) + " |",
+        "| " + " | ".join(["---"] * len(headers)) + " |",
+    ]
+    for row in rows:
+        lines.append("| " + " | ".join(str(row.get(header, "") or "") for header in headers) + " |")
+    return "\n".join(lines)
+
+
+def _write_csv(rows: list[dict[str, Any]], path: Path) -> None:
+    headers = _collect_headers(rows)
+    with path.open("w", encoding="utf-8-sig", newline="") as file:
+        writer = csv.DictWriter(file, fieldnames=headers)
+        writer.writeheader()
+        writer.writerows(rows)
+
+
+def _write_xlsx(rows: list[dict[str, Any]], path: Path) -> None:
+    workbook = openpyxl.Workbook()
+    sheet = workbook.active
+    sheet.title = "客户数据"
+    headers = _collect_headers(rows)
+    sheet.append(headers)
+    for row in rows:
+        sheet.append([row.get(header, "") for header in headers])
+    workbook.save(path)
+
+
+def _collect_headers(rows: list[dict[str, Any]]) -> list[str]:
+    headers: list[str] = []
+    seen: set[str] = set()
+    for row in rows:
+        for key in row.keys():
+            if key not in seen:
+                seen.add(key)
+                headers.append(key)
+    return headers