Refactor/code wiki kb

backend/.env.example

@@ -213,6 +213,11 @@ WIKI_ENABLED=True
 # The team's bot MUST have a model configured (bind_model or custom config)
 # If no model is configured, wiki generation will be disabled in the frontend
 WIKI_DEFAULT_TEAM_NAME=wiki-team
+# Team that runs knowledge-base code wikis (matches init_data/02-public-resources.yaml)
+# Separate from WIKI_DEFAULT_TEAM_NAME: the two paths give their agents different
+# instructions and different submission rules, so they cannot share one team.
+# Its bot MUST have a model configured (bind_model or custom config)
+WIKI_CODE_WIKI_TEAM_NAME=code-wiki-team
 # Default agent type for wiki generation
 WIKI_DEFAULT_AGENT_TYPE=ClaudeCode
 # Default language for wiki documentation generation (en = English, zh = Chinese)

backend/alembic/versions/20260731_bd9c871a93d2_add_knowledge_content_origin_and_wiki_.py

@@ -0,0 +1,77 @@
+"""add knowledge content origin and wiki generation kb link
+
+Revision ID: bd9c871a93d2
+Revises: b9c0d1e2f3a4
+
+Adds the two things a code wiki needs to coexist with ordinary knowledge content:
+
+- ``origin`` on documents and folders, marking whether a row is agent-generated or
+  user-owned. It defaults to ``user`` so that every existing row, and every row this
+  service does not create itself, is excluded from the generated-content projection.
+  Getting this backwards would let a regeneration delete content nobody can restore.
+- ``kind_id`` on wiki generations, binding a version line to a knowledge base. The
+  versions previously hung off ``wiki_projects``, whose ``source_url`` is globally
+  unique; leaving them there would share one version line between knowledge bases
+  tracking the same repository. ``0`` marks rows that predate code wikis.
+
+All three columns are NOT NULL with a server default, as required for existing rows to
+backfill without a nullable intermediate state.
+"""
+
+from collections.abc import Sequence
+from typing import Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "bd9c871a93d2"
+down_revision: Union[str, Sequence[str], None] = "b9c0d1e2f3a4"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    op.add_column(
+        "knowledge_documents",
+        sa.Column(
+            "origin",
+            sa.String(length=20),
+            nullable=False,
+            server_default="user",
+            comment="Content ownership: 'generated' (agent-owned) or 'user'",
+        ),
+    )
+    op.add_column(
+        "knowledge_folders",
+        sa.Column(
+            "origin",
+            sa.String(length=20),
+            nullable=False,
+            server_default="user",
+            comment="Content ownership: 'generated' (agent-owned) or 'user'",
+        ),
+    )
+    op.add_column(
+        "wiki_generations",
+        sa.Column(
+            "kind_id",
+            sa.Integer(),
+            nullable=False,
+            server_default="0",
+            comment="Knowledge base this version line belongs to; 0 = legacy row",
+        ),
+    )
+    op.create_index(
+        "ix_wiki_generations_kind_id", "wiki_generations", ["kind_id"], unique=False
+    )
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    op.drop_index("ix_wiki_generations_kind_id", table_name="wiki_generations")
+    op.drop_column("wiki_generations", "kind_id")
+    op.drop_column("knowledge_folders", "origin")
+    op.drop_column("knowledge_documents", "origin")

backend/app/api/endpoints/knowledge.py

@@ -35,13 +35,17 @@
     AllGroupedKnowledgeResponse,
     BatchDocumentIds,
     BatchOperationResult,
+    CodeWikiCreate,
+    CodeWikiRunCreate,
+    CodeWikiRunResponse,
     DocumentContentUpdate,
     DocumentDetailResponse,
     DocumentMoveRequest,
     InitialMemberCreate,
     KnowledgeBaseCreate,
     KnowledgeBaseListResponse,
     KnowledgeBaseResponse,
+    KnowledgeBaseType,
     KnowledgeBaseTypeUpdate,
     KnowledgeBaseUpdate,
     KnowledgeDocumentCreate,
@@ -64,6 +68,14 @@
     KnowledgeService,
     knowledge_base_qa_service,
 )
+from app.services.knowledge.code_wiki.generation import GenerationInFlight
+from app.services.knowledge.code_wiki.run_mode import ChangedPath
+from app.services.knowledge.code_wiki.runner import CodeWikiRunError, start_run
+from app.services.knowledge.code_wiki.source import (
+    SourceAccessDenied,
+    SourceRepository,
+    assert_user_can_read_source,
+)
 from app.services.knowledge.orchestrator import (
     DEFAULT_KNOWLEDGE_LIST_LIMIT,
     MAX_DOCUMENT_READ_LIMIT,
@@ -424,6 +436,18 @@ def create_knowledge_base(
     - **namespace=<group_name>**: Team knowledge base (requires Maintainer+ permission)
     - **members**: Optional initial members to add after creation
     """
+    # A code wiki must be created through its own endpoint, which binds a repository
+    # and checks the caller can read it. Refusing here rather than quietly ignoring
+    # the field keeps this endpoint from becoming a way around that check.
+    if data.kb_type == KnowledgeBaseType.CODE_WIKI:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=(
+                "Use POST /knowledge-bases/code-wikis to create a "
+                "'code_wiki' knowledge base"
+            ),
+        )
+
     try:
         # Use Orchestrator for unified business logic (REST API and MCP tools share the same logic)
         result = knowledge_orchestrator.create_knowledge_base(
@@ -468,6 +492,138 @@ def create_knowledge_base(
         )
 
 
+@router.post(
+    "/code-wikis",
+    response_model=KnowledgeBaseResponse,
+    status_code=status.HTTP_201_CREATED,
+)
+@trace_sync("create_code_wiki", "knowledge.api")
+def create_code_wiki(
+    data: CodeWikiCreate,
+    current_user: User = Depends(security.get_current_user),
+    db: Session = Depends(get_db),
+):
+    """Create a code wiki bound to a source repository.
+
+    The requester must be able to read the repository, so that a wiki cannot be built
+    for a private repository they have no access to. Reading the resulting wiki is
+    then governed by knowledge-base permissions alone: place it in an organization
+    namespace to make it readable by everyone signed in, or keep it in a restricted
+    namespace and share it explicitly.
+    """
+    try:
+        source = SourceRepository.from_url(data.source_type, data.source_url)
+        assert_user_can_read_source(db, current_user.id, source)
+    except SourceAccessDenied as e:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(e)) from e
+
+    try:
+        result = knowledge_orchestrator.create_knowledge_base(
+            db=db,
+            user=current_user,
+            name=data.name,
+            description=data.description,
+            namespace=data.namespace or "default",
+            kb_type=KnowledgeBaseType.CODE_WIKI.value,
+            source=source,
+        )
+        add_span_event(
+            "knowledge.code_wiki.created",
+            {
+                "kb_id": str(result.id),
+                "project_name": source.project_name,
+                "namespace": data.namespace or "default",
+                "user_id": str(current_user.id),
+            },
+        )
+        return result
+    except IntegrityError as e:
+        db.rollback()
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Knowledge base with name '{data.name}' already exists in this namespace",
+        ) from e
+    except ValueError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)
+        ) from e
+
+
+@router.post(
+    "/{knowledge_base_id}/code-wiki/generations",
+    response_model=CodeWikiRunResponse,
+    status_code=status.HTTP_202_ACCEPTED,
+)
+@trace_sync("start_code_wiki_run", "knowledge.api")
+def start_code_wiki_run(
+    knowledge_base_id: int,
+    data: CodeWikiRunCreate,
+    current_user: User = Depends(security.get_current_user),
+    db: Session = Depends(get_db),
+):
+    """Regenerate a code wiki now, without waiting for its schedule.
+
+    Managing the knowledge base is required rather than merely reading it: a run
+    rewrites every page in it, so this is closer to replacing its content than to
+    viewing it.
+
+    Answers 202 even when no run was needed. "The repository has not changed since the
+    published version" is a successful outcome, not a failure, and the response says
+    which it was.
+    """
+    knowledge_base = KnowledgeService._get_knowledge_base_record(db, knowledge_base_id)
+    if knowledge_base is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Knowledge base not found"
+        )
+    if not KnowledgeService.can_manage_knowledge_base(
+        db, knowledge_base_id, current_user.id
+    ):
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="You do not have permission to regenerate this code wiki",
+        )
+
+    try:
+        started = start_run(
+            db,
+            knowledge_base=knowledge_base,
+            user=current_user,
+            head_commit=data.head_commit,
+            changed_paths=(
+                None
+                if data.changed_paths is None
+                else [
+                    ChangedPath(path=item.path, status=item.change_type)
+                    for item in data.changed_paths
+                ]
+            ),
+        )
+    except GenerationInFlight as e:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(e)) from e
+    except CodeWikiRunError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)
+        ) from e
+
+    add_span_event(
+        "knowledge.code_wiki.run_requested",
+        {
+            "kb_id": str(knowledge_base_id),
+            "started": str(started.started),
+            "mode": started.mode,
+            "user_id": str(current_user.id),
+        },
+    )
+    return CodeWikiRunResponse(
+        started=started.started,
+        mode=started.mode,
+        reason=started.reason,
+        generation_id=started.generation.id if started.generation else 0,
+        task_id=started.task_id,
+    )
+
+
 @router.get("/{knowledge_base_id}", response_model=KnowledgeBaseResponse)
 @trace_sync("get_knowledge_base", "knowledge.api")
 def get_knowledge_base(

backend/app/api/endpoints/wiki.py

@@ -20,6 +20,7 @@
     WikiGenerationDetail,
     WikiGenerationInDB,
     WikiGenerationListResponse,
+    WikiPageRead,
     WikiProjectDetail,
     WikiProjectInDB,
     WikiProjectListResponse,
@@ -217,6 +218,35 @@ def save_wiki_generation_contents(
     return None
 
 
+@internal_router.get("/generations/{generation_id}/pages", response_model=WikiPageRead)
+def read_wiki_generation_page(
+    generation_id: int,
+    path: str = Query(..., min_length=1, description="Stable page path to read"),
+    _: None = Depends(_verify_internal_token),
+    wiki_db: Session = Depends(get_wiki_db),
+):
+    """Read one page of the version the agent is writing into (internal use).
+
+    An incremental version begins as a complete copy of the published wiki, so the
+    agent's own generation is also the current wiki — which makes "read your own
+    version" both the capability it needs and the narrowest scope that provides it.
+    Without this the instruction to revise a page cannot be followed: the agent knows
+    the page's path and cannot see a word of what it says.
+
+    Answers 404 when the path holds no page. That is a useful answer rather than a
+    failure — in an incremental run it means the page is new.
+    """
+    page = wiki_service.get_generation_page(
+        wiki_db=wiki_db, generation_id=generation_id, path=path
+    )
+    if page is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Generation {generation_id} has no page at '{path}'",
+        )
+    return page
+
+
 @router.get(
     "/generations/{generation_id}/contents", response_model=list[WikiContentInDB]
 )

backend/app/core/wiki_config.py

@@ -19,6 +19,13 @@ class WikiSettings(BaseSettings):
         "wiki-team"  # Default execution team name (matches init_data/01-default-resources.yaml)
     )
     DEFAULT_AGENT_TYPE: str = "ClaudeCode"  # Default agent type
+    # Team that runs knowledge-base code wikis (env var: WIKI_CODE_WIKI_TEAM_NAME).
+    # Separate from DEFAULT_TEAM_NAME because the two paths hand their agents
+    # different instructions and different submission rules; pointing both at one team
+    # would give the legacy wiki the page-path write contract it cannot satisfy.
+    CODE_WIKI_TEAM_NAME: str = (
+        "code-wiki-team"  # Matches init_data/02-public-resources.yaml
+    )
     DEFAULT_USER_ID: int = 0  # Default user ID for task creation (0 = use current user)
     DEFAULT_LANGUAGE: str = (
         "en"  # Default language for wiki documentation generation (en/zh)

backend/app/models/knowledge.py

@@ -47,6 +47,22 @@ class DocumentSourceType(str, PyEnum):
     TEXT = "text"  # Pasted text
     TABLE = "table"  # External table (DingTalk, Feishu, etc.)
     WEB = "web"  # Web page (scraped URL)
+    CODE = "code"  # Source file indexed for retrieval, not a browsable document
+
+
+class ContentOrigin(str, PyEnum):
+    """Ownership of knowledge content, deciding whether regeneration may touch it.
+
+    ``GENERATED`` content is owned by the generating agent: it may be overwritten by
+    a later run and removed by generation-set reconciliation. ``USER`` content is
+    owned by a person and is never touched by regeneration.
+
+    ``USER`` is the safe default: mislabelling generated content as user-owned only
+    stops automatic cleanup, while the reverse would expose user content to deletion.
+    """
+
+    GENERATED = "generated"
+    USER = "user"
 
 
 class DocumentIndexStatus(str, PyEnum):
@@ -131,6 +147,14 @@ class KnowledgeDocument(Base):
     source_config = Column(
         JSON, nullable=False, default={}
     )  # Source configuration (e.g., {"url": "..."} for table)
+    # Content ownership; see ContentOrigin. Defaults to ``user`` so that any row this
+    # service did not create is protected from the generated-content projection.
+    origin = Column(
+        String(20),
+        nullable=False,
+        default=ContentOrigin.USER.value,
+        server_default=ContentOrigin.USER.value,
+    )
 
     # --- Helper properties for converted attachment reference ---
 
@@ -210,6 +234,14 @@ class KnowledgeFolder(Base):
     # Self-referencing parent folder, 0 = root level
     parent_id = Column(Integer, nullable=False, default=0)
     name = Column(String(255), nullable=False)
+    # Content ownership; a top-level folder decides ownership for its subtree.
+    # Defaults to ``user`` for the same fail-safe reason as on documents.
+    origin = Column(
+        String(20),
+        nullable=False,
+        default=ContentOrigin.USER.value,
+        server_default=ContentOrigin.USER.value,
+    )
     created_at = Column(DateTime, nullable=False, default=func.now())
     updated_at = Column(
         DateTime, nullable=False, default=func.now(), onupdate=func.now()