wehub-resource-sync
432 lines
19 KiB
Python
432 lines
19 KiB
Python
#!/usr/bin/env python3
|
||
"""Collect project evidence and write a model-authored business context."""
|
||
|
||
from __future__ import annotations
|
||
|
||
import argparse
|
||
import json
|
||
import re
|
||
from pathlib import Path
|
||
from typing import Any
|
||
|
||
from common import ensure_dir, iter_project_files, read_json, read_text, rel, write_json
|
||
|
||
|
||
DOC_EXTS = {".md", ".txt", ".rst", ".adoc"}
|
||
MAX_DOC_CHARS = 80_000
|
||
MAX_DOCS = 40
|
||
|
||
|
||
def normalize_space(text: str) -> str:
|
||
return re.sub(r"\s+", " ", text).strip()
|
||
|
||
|
||
def strip_md(text: str) -> str:
|
||
text = re.sub(r"`{3}.*?`{3}", " ", text, flags=re.S)
|
||
text = re.sub(r"\[(.*?)\]\(.*?\)", r"\1", text)
|
||
text = re.sub(r"[>#*_`|]", " ", text)
|
||
return normalize_space(text)
|
||
|
||
|
||
def skip_doc(path: Path, project: Path) -> bool:
|
||
r = rel(path, project).lower()
|
||
skip_parts = (
|
||
"node_modules",
|
||
".git/",
|
||
"dist/",
|
||
"build/",
|
||
".next/",
|
||
"coverage/",
|
||
"软件著作权申请资料",
|
||
)
|
||
return any(part in r for part in skip_parts)
|
||
|
||
|
||
def extract_headings(text: str, limit: int = 24) -> list[str]:
|
||
headings: list[str] = []
|
||
for line in text.splitlines():
|
||
clean = line.strip()
|
||
if clean.startswith("#"):
|
||
title = clean.lstrip("#").strip()
|
||
if title and title not in headings:
|
||
headings.append(title[:120])
|
||
if len(headings) >= limit:
|
||
break
|
||
return headings
|
||
|
||
|
||
def extract_opening(text: str, limit: int = 900) -> str:
|
||
clean = strip_md(text)
|
||
return clean[:limit].strip()
|
||
|
||
|
||
def collect_documents(project: Path) -> list[dict[str, Any]]:
|
||
docs: list[dict[str, Any]] = []
|
||
for path in iter_project_files(project, DOC_EXTS):
|
||
if skip_doc(path, project):
|
||
continue
|
||
try:
|
||
text = read_text(path, limit=MAX_DOC_CHARS)
|
||
except Exception:
|
||
continue
|
||
if not text.strip():
|
||
continue
|
||
docs.append(
|
||
{
|
||
"path": rel(path, project),
|
||
"size": path.stat().st_size,
|
||
"headings": extract_headings(text),
|
||
"opening": extract_opening(text),
|
||
}
|
||
)
|
||
docs.sort(key=lambda item: (item["path"].count("/"), item["path"]))
|
||
return docs[:MAX_DOCS]
|
||
|
||
|
||
def collect_code_evidence(analysis: dict[str, Any]) -> dict[str, Any]:
|
||
source = analysis.get("source") or {}
|
||
categorized = source.get("categorized_files") or {}
|
||
return {
|
||
"project_name": analysis.get("project_name"),
|
||
"software_name_candidate": analysis.get("software_name_candidate"),
|
||
"frameworks": analysis.get("frameworks") or [],
|
||
"language": analysis.get("language"),
|
||
"routes": analysis.get("routes") or [],
|
||
"feature_name_candidates": analysis.get("feature_candidates") or [],
|
||
"entry_files": categorized.get("entry") or [],
|
||
"page_files": categorized.get("page") or [],
|
||
"component_files": categorized.get("component") or [],
|
||
"api_files": categorized.get("api") or [],
|
||
"run_command_candidates": analysis.get("run_command_candidates") or [],
|
||
"package": analysis.get("package") or {},
|
||
}
|
||
|
||
|
||
def build_evidence(project: Path, analysis: dict[str, Any], software_name: str, web_notes: str) -> dict[str, Any]:
|
||
return {
|
||
"software_name": software_name,
|
||
"project_root": str(project.resolve()),
|
||
"instruction": (
|
||
"本文件只收集证据，不决定行业、功能或手册结构。"
|
||
"请由模型阅读这些证据以及必要的项目源码后，另行编写业务理解模型稿。"
|
||
),
|
||
"documents": collect_documents(project),
|
||
"code_evidence": collect_code_evidence(analysis),
|
||
"external_research_notes": web_notes,
|
||
}
|
||
|
||
|
||
def write_evidence_md(path: Path, evidence: dict[str, Any]) -> None:
|
||
lines = [
|
||
"# 业务理解证据",
|
||
"",
|
||
f"- 软件名称：{evidence['software_name']}",
|
||
f"- 项目目录：`{evidence['project_root']}`",
|
||
"",
|
||
"本文件只列出可供模型研判的项目证据，不代表最终申报口径。",
|
||
"模型需要自行判断应阅读哪些文档、抽取哪些功能、采用什么操作手册结构。",
|
||
"",
|
||
"## 代码与页面证据",
|
||
"",
|
||
]
|
||
code = evidence["code_evidence"]
|
||
for key in ("frameworks", "language", "routes", "feature_name_candidates", "entry_files", "page_files", "component_files", "api_files"):
|
||
value = code.get(key)
|
||
if value:
|
||
lines.append(f"- {key}：{value}")
|
||
lines.extend(["", "## 文档证据", ""])
|
||
for doc in evidence["documents"]:
|
||
lines.extend(
|
||
[
|
||
f"### {doc['path']}",
|
||
"",
|
||
f"- 大小：{doc['size']} bytes",
|
||
f"- 标题线索：{'；'.join(doc['headings']) if doc['headings'] else '无'}",
|
||
"",
|
||
doc["opening"],
|
||
"",
|
||
]
|
||
)
|
||
if evidence.get("external_research_notes"):
|
||
lines.extend(["## 外部调研摘要", "", evidence["external_research_notes"], ""])
|
||
path.write_text("\n".join(lines), encoding="utf-8")
|
||
|
||
|
||
def write_model_template(path: Path, evidence: dict[str, Any]) -> None:
|
||
template = {
|
||
"software_name": evidence["software_name"],
|
||
"product_positioning": "",
|
||
"industry": "",
|
||
"target_users": [],
|
||
"core_value": "",
|
||
"business_features": [],
|
||
"business_feature_details": {},
|
||
"operation_flow": [],
|
||
"application_purpose": "",
|
||
"main_functions": "",
|
||
"technical_characteristics": "",
|
||
"software_technical_option": "应用软件",
|
||
"software_category": "应用软件",
|
||
"manual_sections": [
|
||
{
|
||
"title": "模型自行命名章节",
|
||
"intent": "说明该章节为什么适合当前项目。",
|
||
"paragraphs": [],
|
||
"include_feature_overview": False,
|
||
"include_operation_modules": False,
|
||
"include_operation_flow": False,
|
||
}
|
||
],
|
||
"manual_modules": [
|
||
{
|
||
"title": "真实页面或核心流程名称",
|
||
"evidence": ["页面、路由、组件、README 或需求文档路径"],
|
||
"purpose": "该页面或流程在当前软件中的用途。",
|
||
"usage": "用户在什么业务场景下会使用该页面，正在处理什么具体事务。",
|
||
"entry": "用户从哪里进入该页面或流程。",
|
||
"visible_elements": ["用户实际能看到的输入框、按钮、列表、状态或结果区域"],
|
||
"operation_steps": ["按真实页面顺序描述用户动作，不写代码实现。"],
|
||
"validation_rules": ["输入限制、必填项、额度、权限、异常提示等规则；没有则留空数组。"],
|
||
"feedback": ["操作完成后用户能看到的结果、提示或状态变化。"],
|
||
"screenshot": "截图预留说明",
|
||
}
|
||
],
|
||
"system_requirements": [
|
||
{"item": "操作系统", "minimum": "按项目实际填写", "recommended": "按项目实际填写"},
|
||
{"item": "浏览器或客户端", "minimum": "按项目实际填写", "recommended": "按项目实际填写"},
|
||
],
|
||
"faq": [
|
||
{"question": "按当前软件真实使用场景填写常见问题", "answer": "给出面向普通用户的处理方法。"}
|
||
],
|
||
"glossary": [
|
||
{"term": "当前软件中的业务术语", "definition": "用普通中文解释含义。"}
|
||
],
|
||
"model_review_notes": [
|
||
"操作手册应采用软著审核友好的通用骨架：相关文档、说明、功能特点、系统要求、按真实页面/流程逐章操作、常见问题、术语表。",
|
||
"manual_modules 要按当前项目真实页面、导航入口、按钮、输入限制、系统反馈和截图位置编写，不能只写抽象功能名。",
|
||
"不要照抄范本文案；范本只说明手册需要具体、可操作、能给审核员看懂。",
|
||
"不要用关键词表决定行业和功能；必须能从项目证据或用户补充中解释来源。",
|
||
],
|
||
}
|
||
write_json(path, template)
|
||
|
||
|
||
def load_model_context(path: Path) -> dict[str, Any]:
|
||
data = read_json(path)
|
||
if not isinstance(data, dict):
|
||
raise SystemExit(f"Invalid model context JSON: {path}")
|
||
return data
|
||
|
||
|
||
def required_list(value: Any, field: str) -> list[str]:
|
||
if not isinstance(value, list):
|
||
raise SystemExit(f"Model context field must be a list: {field}")
|
||
items = [str(item).strip() for item in value if str(item).strip()]
|
||
if not items:
|
||
raise SystemExit(f"Model context field cannot be empty: {field}")
|
||
return items
|
||
|
||
|
||
def required_text(data: dict[str, Any], field: str) -> str:
|
||
value = str(data.get(field) or "").strip()
|
||
if not value:
|
||
raise SystemExit(f"Model context field cannot be empty: {field}")
|
||
return value
|
||
|
||
|
||
def normalize_model_context(model: dict[str, Any], evidence: dict[str, Any], web_notes: str) -> dict[str, Any]:
|
||
features = required_list(model.get("business_features"), "business_features")
|
||
details = model.get("business_feature_details") or {}
|
||
if not isinstance(details, dict):
|
||
raise SystemExit("Model context field must be an object: business_feature_details")
|
||
missing = [feature for feature in features if not str(details.get(feature) or "").strip()]
|
||
if missing:
|
||
raise SystemExit("Model context missing feature details: " + "、".join(missing[:12]))
|
||
sections = model.get("manual_sections") or []
|
||
if sections and not isinstance(sections, list):
|
||
raise SystemExit("Model context field must be a list: manual_sections")
|
||
manual_modules = model.get("manual_modules") or []
|
||
if manual_modules and not isinstance(manual_modules, list):
|
||
raise SystemExit("Model context field must be a list: manual_modules")
|
||
if not manual_modules:
|
||
raise SystemExit("Model context field cannot be empty: manual_modules")
|
||
for index, module in enumerate(manual_modules, start=1):
|
||
if not isinstance(module, dict):
|
||
raise SystemExit(f"manual_modules item {index} must be an object")
|
||
title = str(module.get("title") or module.get("feature") or "").strip()
|
||
for field in ("purpose", "usage", "entry", "operation_steps", "feedback"):
|
||
value = module.get(field)
|
||
if field == "usage" and not str(value or "").strip():
|
||
value = module.get("usage_scenario")
|
||
if isinstance(value, list):
|
||
missing_value = not any(str(item).strip() for item in value)
|
||
else:
|
||
missing_value = not str(value or "").strip()
|
||
if missing_value:
|
||
raise SystemExit(f"manual_modules item {index} ({title or 'untitled'}) missing field: {field}")
|
||
system_requirements = model.get("system_requirements") or []
|
||
if system_requirements and not isinstance(system_requirements, list):
|
||
raise SystemExit("Model context field must be a list: system_requirements")
|
||
if not system_requirements:
|
||
raise SystemExit("Model context field cannot be empty: system_requirements")
|
||
faq = model.get("faq") or []
|
||
if faq and not isinstance(faq, list):
|
||
raise SystemExit("Model context field must be a list: faq")
|
||
if not faq:
|
||
raise SystemExit("Model context field cannot be empty: faq")
|
||
glossary = model.get("glossary") or []
|
||
if glossary and not isinstance(glossary, list):
|
||
raise SystemExit("Model context field must be a list: glossary")
|
||
if not glossary:
|
||
raise SystemExit("Model context field cannot be empty: glossary")
|
||
context = {
|
||
"software_name": evidence["software_name"],
|
||
"business_understanding_required": True,
|
||
"source_documents": [{"path": doc["path"], "size": doc["size"]} for doc in evidence["documents"]],
|
||
"project_evidence_file": "业务理解证据.md",
|
||
"product_positioning": required_text(model, "product_positioning"),
|
||
"industry": required_text(model, "industry"),
|
||
"target_users": required_list(model.get("target_users"), "target_users"),
|
||
"core_value": required_text(model, "core_value"),
|
||
"business_features": features,
|
||
"business_feature_details": {feature: str(details.get(feature)).strip() for feature in features},
|
||
"operation_flow": required_list(model.get("operation_flow"), "operation_flow"),
|
||
"application_purpose": required_text(model, "application_purpose"),
|
||
"main_functions": required_text(model, "main_functions"),
|
||
"technical_characteristics": required_text(model, "technical_characteristics"),
|
||
"software_technical_option": str(model.get("software_technical_option") or "应用软件"),
|
||
"software_category": str(model.get("software_category") or "应用软件"),
|
||
"manual_sections": sections,
|
||
"manual_modules": manual_modules,
|
||
"system_requirements": system_requirements,
|
||
"faq": faq,
|
||
"glossary": glossary,
|
||
"model_authored": True,
|
||
"external_research_notes": web_notes,
|
||
"confirmation_required": True,
|
||
"user_confirmed": False,
|
||
"confirmation_stage": "business",
|
||
"next_action": "请确认 草稿/业务理解.md 中的软件用途、行业、目标用户、核心功能、手册结构和申请口径；确认后运行 confirm_stage.py --stage business。",
|
||
"review_notes": [
|
||
"请确认模型判断的行业领域、目标用户和主要功能是否符合实际申报口径。",
|
||
"请确认操作手册结构是否按真实页面和流程展开，而不是套用抽象功能列表。",
|
||
],
|
||
}
|
||
return context
|
||
|
||
|
||
def write_context_md(path: Path, context: dict[str, Any]) -> None:
|
||
lines = [
|
||
"# 业务理解",
|
||
"",
|
||
f"- 软件名称：{context['software_name']}",
|
||
f"- 产品定位：{context['product_positioning']}",
|
||
f"- 面向领域 / 行业：{context['industry']}",
|
||
f"- 核心价值：{context['core_value']}",
|
||
f"- 证据文件：`{context['project_evidence_file']}`",
|
||
"",
|
||
"## 目标用户",
|
||
"",
|
||
]
|
||
lines.extend(f"- {item}" for item in context["target_users"])
|
||
lines.extend(["", "## 主要业务功能", ""])
|
||
lines.extend(f"- {item}" for item in context["business_features"])
|
||
lines.extend(["", "## 功能说明", ""])
|
||
for item in context["business_features"]:
|
||
lines.append(f"- {item}：{context['business_feature_details'].get(item, '')}")
|
||
lines.extend(["", "## 典型操作流程", ""])
|
||
lines.extend(f"{i}. {item}" for i, item in enumerate(context["operation_flow"], start=1))
|
||
if context.get("manual_sections"):
|
||
lines.extend(["", "## 操作手册结构建议", ""])
|
||
for i, section in enumerate(context["manual_sections"], start=1):
|
||
if isinstance(section, dict):
|
||
title = section.get("title") or f"章节 {i}"
|
||
intent = section.get("intent") or ""
|
||
else:
|
||
title = str(section)
|
||
intent = ""
|
||
lines.append(f"{i}. {title}" + (f"：{intent}" if intent else ""))
|
||
if context.get("manual_modules"):
|
||
lines.extend(["", "## 操作手册页面/流程模块", ""])
|
||
for i, module in enumerate(context["manual_modules"], start=1):
|
||
if not isinstance(module, dict):
|
||
lines.append(f"{i}. {module}")
|
||
continue
|
||
title = module.get("title") or module.get("feature") or f"模块 {i}"
|
||
usage = module.get("usage") or module.get("usage_scenario") or ""
|
||
entry = module.get("entry") or ""
|
||
steps = module.get("operation_steps") or module.get("steps") or []
|
||
lines.append(f"{i}. {title}" + (f"：{entry}" if entry else ""))
|
||
if usage:
|
||
lines.append(f" - 使用场景：{usage}")
|
||
if steps:
|
||
lines.append(f" - 操作要点：{'；'.join(str(item) for item in steps[:4])}")
|
||
lines.extend(
|
||
[
|
||
"",
|
||
"## 申请表建议口径",
|
||
"",
|
||
f"- 开发目的：{context['application_purpose']}",
|
||
f"- 软件的主要功能：{context['main_functions']}",
|
||
f"- 技术特点：{context['technical_characteristics']}",
|
||
f"- 软件的技术特点选项：{context['software_technical_option']}",
|
||
f"- 软件分类：{context['software_category']}",
|
||
"",
|
||
"## 证据来源",
|
||
"",
|
||
]
|
||
)
|
||
lines.extend(f"- `{item['path']}`" for item in context["source_documents"])
|
||
lines.extend(["", "## 待确认", ""])
|
||
lines.extend(f"- {item}" for item in context["review_notes"])
|
||
lines.extend(
|
||
[
|
||
"",
|
||
"```text",
|
||
"STOP_FOR_USER",
|
||
f"NEXT_ACTION: {context['next_action']}",
|
||
"```",
|
||
]
|
||
)
|
||
path.write_text("\n".join(lines) + "\n", encoding="utf-8")
|
||
|
||
|
||
def main() -> None:
|
||
parser = argparse.ArgumentParser()
|
||
parser.add_argument("--project", required=True)
|
||
parser.add_argument("--analysis", required=True)
|
||
parser.add_argument("--software-name", required=True)
|
||
parser.add_argument("--out-dir", default="软件著作权申请资料/草稿")
|
||
parser.add_argument("--web-notes", help="Optional plain-text notes from external/competitor research")
|
||
parser.add_argument("--model-context", help="Model-authored business context JSON")
|
||
args = parser.parse_args()
|
||
|
||
project = Path(args.project)
|
||
analysis = read_json(Path(args.analysis))
|
||
web_notes = read_text(Path(args.web_notes)) if args.web_notes else ""
|
||
out_dir = ensure_dir(Path(args.out_dir))
|
||
|
||
evidence = build_evidence(project, analysis, args.software_name, web_notes)
|
||
write_json(out_dir / "业务理解证据.json", evidence)
|
||
write_evidence_md(out_dir / "业务理解证据.md", evidence)
|
||
|
||
if not args.model_context:
|
||
write_model_template(out_dir / "业务理解模型稿模板.json", evidence)
|
||
print(f"OK business evidence: {out_dir / '业务理解证据.md'}")
|
||
print(f"OK model template: {out_dir / '业务理解模型稿模板.json'}")
|
||
print("NEXT_ACTION: 模型需要阅读业务理解证据和项目源码，自行编写业务理解模型稿 JSON，然后用 --model-context 生成业务理解.md/json。")
|
||
return
|
||
|
||
model = load_model_context(Path(args.model_context))
|
||
context = normalize_model_context(model, evidence, web_notes)
|
||
write_json(out_dir / "业务理解.json", context)
|
||
write_context_md(out_dir / "业务理解.md", context)
|
||
print(f"OK business context: {out_dir / '业务理解.md'}")
|
||
print(f"Features: {len(context['business_features'])}")
|
||
print("STOP_FOR_USER")
|
||
print(f"NEXT_ACTION: {context['next_action']}")
|
||
|
||
|
||
if __name__ == "__main__":
|
||
main()
|